OAuth2 Clients

Schema der OAuth2 Clients

As a contributor, you can manage OAuth2 Clients via the mStudio API. The required routes are described in the Guide to Managing OAuth2 Clients.

Below, the required parameters are explained in more detail.

Schema documentation

• idstring (uuid)

  required

  The ID of the OAuth2 Client. It has to be unique and identical to the Extension ID

• humanReadableNamestring

  required

  Name of the OAuth2 Client. It should be identical to the Extension name

• grantTypesarray of "authorization_code"

  required

  Allowed OAuth2 grant types. Currently, only authorization_code (with PKCE flow) is allowed

  • Array[
  • *"authorization_code"
  ]

scopesarray of string

required

Allowed scopes, the client can request.

• Array[
• *string
]

redirectURIsarray of string (uri)

required

Allowed redirect URIs, the client is allowed to use.

• Array[
• *string (uri)
]

Example

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": "The ID of the OAuth2 Client. It has to be unique and identical to the Extension ID"
    },
    "humanReadableName": {
      "type": "string",
      "description": "Name of the OAuth2 Client. It should be identical to the Extension name"
    },
    "grantTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "authorization_code"
        ]
      },
      "description": "Allowed OAuth2 grant types. Currently, only authorization_code (with PKCE flow) is allowed"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Allowed scopes, the client can request.",
      "example": [
        "mail:read",
        "mail:write",
        "project:read"
      ]
    },
    "redirectURIs": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "description": "Allowed redirect URIs, the client is allowed to use.",
      "example": [
        "https://example.com/oauth2/callback",
        "http://localhost:3000/oauth2/callback"
      ]
    }
  }
}

allowedScopes

The scopes that the client may request. The client does not have to request all scopes. If the OAuth2 Client is used for an Extension, the scopes of the OAuth2 Client do not have to be identical to the scopes of the Extension. In many cases, it makes sense that the scopes differ.

For example, one such case is that an Extension might only do reading and not writing operations without user interaction. The writing operations are then executed by an mStudio User using the Extension with the help of OAuth2.

allowedRedirectURIs

The redirect URIs that the client may use. If the authorization server allows only one redirect URI, the client does not have to specify a redirect_uri, as describen in RFC 6749. However, if the authorization server allows multiple redirect URIs, the client must specify a redirect_uri that is identical to one of the allowed URIs.

Templating is not supported for the redirect URIs to avoid common gaps in the OAuth2 implementation. The mStudio makes a simple string comparison to validate, whether an URI is allowed. The URI string contains the protocol, the complete domain, the port, and the path of the URI.

It makes sense to allow http://localhost as redirect URI to make local testing possible. You have to ensure that the correct port is configured, as mentioned above.