OAuth2 Clients

Schema der OAuth2 Clients

Als Contributor kannst du OAuth2 Clients über die mStudio API verwalten. Die benötigten Routen sind in Anleitung zur Verwaltung von OAuth2-Clients beschrieben.

Im folgenden werden die benötigten Parameter genauer beschrieben.

Schema-Dokumentation

• idstring (uuid)

  required

  ID des OAuth2 Clients, muss eindeutig sein und mit der Extension ID übereinstimmen

• humanReadableNamestring

  required

  Name des OAuth2 Clients, sollte mit dem Namen der Extension übereinstimmen

• grantTypesarray of "authorization_code"

  required

  Erlaubte OAuth2 Grant Types, derzeit ist nur authorization_code (mit PKCE Verfahren) erlaubt

  • Array[
  • *"authorization_code"
  ]

scopesarray of string

required

Erlaubte Scopes, die der Client anfordern kann.

• Array[
• *string
]

redirectURIsarray of string (uri)

required

Erlaubte Redirect URIs, die der Client verwenden kann.

• Array[
• *string (uri)
]

Beispiel

{
  "id": "f0f86186-0a5a-45b2-aa33-502777496347",
  "humanReadableName": "string",
  "grantTypes": [
    "authorization_code"
  ],
  "scopes": [
    "mail:read",
    "mail:write",
    "project:read"
  ],
  "redirectURIs": [
    "https://example.com/oauth2/callback",
    "http://localhost:3000/oauth2/callback"
  ]
}

JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "humanReadableName",
    "grantTypes",
    "scopes",
    "redirectURIs"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "ID des OAuth2 Clients, muss eindeutig sein und mit der Extension ID übereinstimmen"
    },
    "humanReadableName": {
      "type": "string",
      "description": "Name des OAuth2 Clients, sollte mit dem Namen der Extension übereinstimmen"
    },
    "grantTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "authorization_code"
        ]
      },
      "description": "Erlaubte OAuth2 Grant Types, derzeit ist nur authorization_code (mit PKCE Verfahren) erlaubt"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Erlaubte Scopes, die der Client anfordern kann.",
      "example": [
        "mail:read",
        "mail:write",
        "project:read"
      ]
    },
    "redirectURIs": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "description": "Erlaubte Redirect URIs, die der Client verwenden kann.",
      "example": [
        "https://example.com/oauth2/callback",
        "http://localhost:3000/oauth2/callback"
      ]
    }
  }
}

scopes

Die Scopes, die der Client anfragen kann. Der Client muss nicht alle Scopes anfragen. Wenn OAuth2 Clients in Kombination einer Extension verwendet werden, müssen die Scopes des OAuth2 Clients nicht zwingend mit denen der Extension übereinstimmen. In vielen Fällen kann es Sinn ergeben, dass die Scopes abweichen.

Ein Beispiel für Abweichungen wäre, dass die Extension ohne Nutzinteraktionen keine schreibenden Operationen durchführt, sondern lediglich gewisse notwendige Daten ausliest und alle schreibenden Operationen über einen mStudio Nutzer und OAuth2 durchgeführt werden.

redirectURIs

Die Redirect URIs, die der Client verwenden kann. Wie im RFC 6749 beschrieben, muss der Client keine redirect_uri beim Authorization Request angeben, wenn der Authorization Server nur eine Redirect URI erlaubt. Wenn jedoch mehrere Redirect URIs erlaubt sind, muss der Client eine redirect_uri angeben, die vollständig mit einer der erlaubten URIs übereinstimmt.

Für die Redirect URIs wird ausdrücklich kein Templating unterstützt, um gängige Lücken in OAuth2 Implementierungen zu vermeiden. Zur Prüfung, ob eine URI erlaubt ist, wird ein einfacher String-Vergleich durchgeführt. Dieser beinhaltet das Protokoll, die vollständige Domain, den Port und den Pfad der URI.

Für lokale Testzwecke kann es sinnvoll sein, http://localhost als Redirect URI zu erlauben. Dabei muss darauf geachtet werden, dass, wie bereits erwähnt, der Port ebenfalls übereinstimmen muss.