SCIM 2.0 API authentication
- Kai Bjørnstad (Deactivated)
The SCIM 2.0 protocol support multiple HTTP-based authentication schemes to enable API access by some SCIM client. However, only one method is supported by the Buypass SCIM implementations.
OAuth2 Bearer Token
For all OpenID Security Domains , Buypass only support the SCIM authentication scheme of “oauthbearertoken” (OAuth2 Bearer Token). And needless to say, only HTTPS based communication is allowed.
This will also be reflected by the “/ServiceProviderConfig” endpoint:
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
"documentationUri": "https://developer.buypass.com/",
"authenticationSchemes": [
{
"name": "OAuth2 Bearer Token",
"description":
"Authentication scheme using the OAuth2 Bearer Token Standard",
"specUri": "https://tools.ietf.org/html/rfc6750",
"documentationUri": "https://developer.buypass.com/",
"type": "oauthbearertoken",
"primary": true
},
...Using the OAuth2 Bearer Token scheme enable the authentications to be delegated to a OAuth2/OIDC server outside of the SCIM API implementation. This also make the authentication mechanism compatible with Authentication with OIDC, both client only authentication (Client authentication) and end-user authentication OIDC Flows. Note that all best security practises related to bearer tokens (like TLS transport, limited scoping, short lifetimes) are enforced.
As described in RFC 7644, section-2.1, enable SCIM client system to act on:
behalf of themselves (using the OAuth2 Client Credential Grant)
behalf of an end-user (using standard OIDC Authorization Code Flow)
In the following example, a client sends a POST request containing a"User" to the "/Users" endpoint using a Bearer token for authentication (retrieving the token from the OAuth2/OIDC server is excluded).
POST /<SECURITY DOMAIN>/scim/v2/ HTTP/1.1
Host: api.buypass.no
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen",
"familyName":"Jensen",
"givenName":"Barbara"
}
}Retrieving a token
The OAuth2 and OIDC processes for authenticating and retrieveing tokens ar well described here: token. However, make note of needed authorization and scoping described below.
Authorization and Scoping
In accordance with the SCIM specification (RFC 7644, section-2.1), Scopes are used to give the bearer token (and hence the SCIM client) a representation of an authorization. These scopes are Buypass and SCIM API specific and the authorizations they imply are enforced by the SCIM api implementation. The SCIM client must request an Access Token with the appropriate scope. The issuance of such a token is governed by the OIDC/OAuth2 server.
Note that the granularity of authorization needed may differ with the various OpenID Security Domains and their applications.
Standard SCIM API scope to control read, write and delete functionality in the API:
Functionality | Scope |
|---|---|
Read data | scim.read |
Write/edit/delete data | scim.write |