OAuth 2.0 and OpenID Connect setup
Client registration
To register an OAuth client with the OneWelcome Identity Platform, the following information is needed:
| Client Information | Remarks |
|---|---|
| client_id | The client identifier issued to the client during the registration process. |
| type | Confidential clients can maintain the confidentiality of their credentials, such as a web application running on a server where its credentials are protected. Public clients run the risk of exposing their passwords to a host or user agent, such as a JavaScript client running in a browser. |
| standard | OAuth 2.0 and OIDC 1.0 |
| client secret | \u2705 Basic authentication is supported. So, for confidential clients, you must configure a client secret. >No other client authentication methods than basic authentication or Client_Id and Client_Secret POST are supported. |
| redirect URIs | One or multiple redirect-URIs. >Only applicable for the implicit grant and authorization code grant. |
| scope whitelist | One or multiple scopes. The OneWelcome Identity Platform only issues access tokens for allow-listed scopes. |
| default scopes | Optionally, one or multiple default scopes can be configured. The OneWelcome Identity Platform returns these in any successful access token response. |
Note
The registration of clients is executed by the OneWelcome Identity Platform's technical consultants. The OneWelcome Identity Platform currently does not provide an API, nor an administration app to its customers.
Use of scopes
The OneWelcome Identity Platform allows you to configure an allow-list of scopes per client application. Whenever a client requests authorization for one or more scopes, the OneWelcome Identity Platform does not grant an access token if the request contains a scope that is not on the allow-list.
If all requested scopes are allow-listed, they are returned in the access token response (that is, in the response message, because the access token itself is opaque and doesn't contain the scopes). The OneWelcome Identity Platform also supports configuring a list of default scopes per client application.
All the default scopes are included in a successful access token response, so the OAuth client can get more scopes than requested. If no default scopes are configured and no scope is requested, the OneWelcome Identity Platform returns an error response.
Include any user identifiers whose user-specific values are needed by the resource server.
Note
The OneWelcome Identity Platform recommends defining a distinct scope for each API or resource server that will be invoked by the client (for example, AuthorisationToDownloadPhotos) to make explicit what kind of access the client wants to have. In situations where multiple resource servers are linked to the OneWelcome Identity Platform with OAuth, a resource server can deny access if an access token is presented that was not issued with the appropriate scope.
Note
The OneWelcome Identity Platform does not support the ability to present a list of (requested) scopes to the user and let the user give consent on a selection of scopes.
Redirection and usage of State parameter
After access is granted, you might want the user to be redirected to some URL at the resource server. The OneWelcome Identity Platform can do so, when the implicit grant flow or the authorization code grant flow is used.
Mechanisms to facilitate redirection
Single redirect URI
For OAuth clients that use the authorization code grant flow, a redirection URI can be configured into the OneWelcome Identity Platform.
Redirect URI allow-listing
For OAuth clients that use more than one redirection URI, multiple redirect URIs can be configured in the OneWelcome Identity Platform. These are used as an allow-list. During execution of a flow, the applicable redirection URI must then be submitted in the authorization request. If the request includes a redirection URI, the OneWelcome Identity Platform compares it with the configured redirection URI allow-list.
Redirect URI with state
OAuth clients that want to redirect to a huge range of URIs (for example a web shop where an individual product needs to be included in the redirect URI), can make use of the state parameter. Doing so is recommended by rfc6749 - OAuth 2.0 for both the authorization code grant flow and the implicit grant flow to prevent phishing attacks. When comparing a redirection URI with the redirection URI allow-list, URL parameters are not taken into consideration. If the redirection URI is allow-listed, the OneWelcome Identity Platform passes the state parameter and the application can use it as a session key.
Note
Be aware that the redirection URI must NOT contain a fragment (#). It must be an absolute path and it cannot contain wildcards.
The state parameters SHOULD NOT include sensitive client or resource owner information in plain text, because they can be transmitted over insecure channels or stored insecurely. Instead the value of the state parameter should be opaque and the application should maintain a table with combinations of states and session-information, such as redirection.
