Setup
Client Registration
To register an OAuth client at OneWelcome 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 | ✅ Basic Authentication is supported. So for confidential clients, you must configure a client secret. No other client authentication methods then Basic Authentication or Client_Id and Client_Secret POST are supported. Support for client authentication or passing requests parameters in assertions, as specified in [ OAuth Client Assertions ] will possibly be added in the near future. |
| redirect URIs | One or multiple redirect-URIs. Only applicable for Implicit Grant and Authorisation Code Grant. |
| scope whitelist | One or multiple scopes. OneWelcome will only issues access tokens for whitelisted scopes. |
| default scopes | Optionally one or multiple default scopes can be configured. OneWelcome returns these in any successful access token response. |
Caution: The registration of clients is executed by OneWelcome's technical consultants. OneWelcome currently does not provide an API, nor an administration app to its customers.
Usage of Scopes
OneWelcome allows you to configure a whitelist of 'scopes' per client application. Whenever a client requests authorisation for one or more scopes, OneWelcome will not grant an access token if the request contains a scope that is not on the whitelist.
If all requested scopes are whitelisted those are returned in the access token response (i.e. in the response message, as the access token itself is opaque and doesn't contain the scopes). OneWelcome 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 may get more scopes than requested. If no default scopes are configured and no scope is requested, OneWelcome returns an error response.
Include any user identifiers whose user-specific values are needed by Resource server, see also section TokenInfo Endpoint.
Note OneWelcome 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 OneWelcome with OAuth, a Resource Server may choose to deny access if an access token is presented that was not issued with the appropriate scope.
Caution OneWelcome does not currently support the ability to present a list of (requested) scopes to the end user and let the end user give consent on a selection of scopes.
Redirection and Usage of 'State' Parameter
After access is granted, you may want the user to be redirected to some URL at the Resource Server. OneWelcome can do so, when the Implicit Grant flow or the Authorisation Code Grant flow is used.
OneWelcome has the following mechanisms to facilitate redirection:
Single redirect URI
For OAuth clients that use the Authorisation Code Grant flow, a redirection URI can be configured into OneWelcome.
Redirect URI whitelisting
For OAuth clients that use more than one redirection URI, multiple redirect URIs can be configured in OneWelcome. These are used as a whitelist. During execution of a flow, the applicable redirection URI must then be submitted in the authorisation request. If the request includes a redirection URI, OneWelcome compares it with the configured redirection URI whitelist.
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 Authorisation Code Grant flow and the Implicit Grant flow to prevent 'phishing' attacks. When comparing a redirection URI with the redirection URI whitelist, URL parameters are not taken into consideration. If the redirection URI is whitelisted, OneWelcome passes the state parameter and the application can use it as a session key.
Caution Please be aware that the redirection URI must NOT contain a fragment (#). It must be an absolute path and it cannot contain 'wildcards'.
Note The 'state' parameters SHOULD NOT include sensitive client or resource owner information in plain text, as 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.