BAS SCIM API documentation
- Stine Granviken
Preregistration and update Userinfo using the Scim-api
(In English only)
Identity Management and Provisioning - general documentation about provisioning and using the SCIM api.
Access SCIM API is a separate API for provisioning end-users to Buypass Access Solution - BAS.
Base URLs
Environment | URL |
|---|---|
production | https://api.buypass.no/access-scim-api
|
test4 | https://api.test4.buypass.no/access-scim-api
|
Scim-api Docs - test4 | https://api.test4.buypass.no/access-scim-api gives redirect to swagger, or
|
API Endpoints
Endpoint | Description |
|---|---|
/Tenants/{tenant_id}/Users | Retrieve, add and modify users. |
/Schemas | Retrieve one or more supported schemas. |
/ResourceTypes | Retrieve supported resource types. |
/ServiceProviderConfig | An HTTP GET to this endpoint will return a JSON structure that describes the SCIM specification features available on a service provider. |
API Schemas
urn:ietf:params:scim:schemas:core:2.0:User
urn:ietf:params:scim:schemas:extension:buypass:2.0:upn:User
Core
Field | Description | Example | Required | Mutablitity |
|---|---|---|---|---|
userName | Unique identifier for the user, used by the user to directly authenticate with the service provider. Must be the Norwegian National Person Identifier. | "userName" : "01026201590" | Required | Immutable |
externalId | An identifier for the User as defined by the customer | "externalId": "701984" | Required | ReadWrite |
name | The user's real name | "name": {
"familyName": "Jensen",
"givenName": "Barbara",
"middleName": "Jane"
}
| Required | ReadOnly |
phoneNumbers | The user's phone number in E.164 format. Only one phone number is supported | Optional | ReadWrite | |
emails | The user's email address. Only one email address is supported. | Optional | ReadWrite | |
entitlements | Array of one or more entitlement values that this user has. Supported entitlement values are:
If no entitlements are provided the default settings for the Tenant takes effect. | Optional | ReadWrite | |
active | A Boolean value indicating whether a user is active. Only active users is supported. | Optional | ReadOnly |
UPN
Field | Description | Example | Required | Mutablitity |
|---|---|---|---|---|
upn | The name of the user in email address format | Optional | ReadWrite |
API Access Token
Provided for BAS-Merchant when the use of the scim for provisioning has been agreed. See next section.
Client ID | Environment | Tenant ID | SCIM API Access token request |
|---|---|---|---|
<tenant>-scim-api-client | TEST4 | <tenant-ID> | curl -i -H "Content-Type: application/x-www-form-urlencoded" -X POST "https://auth.tsp.buypass.no/auth/realms/buypassid/protocol/openid-connect/token" -d "grant_type=client_credentials&client_id=<tenant>-scim-api-client&client_secret=<clientsecret>" |
Content:
BAS SCIM Token
Norsk:
AD kan implementeres på en av følgende tre varianter:
AD lokalt
AD hybrid – AD lokalt med «skygge-overføring» til Azure – her er AD lokalt master med en kopi i skyen
AD Azure
AD lokalt og hybrid har støtte for bruk av dynamiske token som er det Buypass har implementer ved bruk av scim-api *.
AD Azure har scim-provisioning som egen feature, men denne kan standard kun settes opp med Secret Token som er et statisk passord, men det er også med bruk av AD Gallery åpnet for bruk av ClientID / Client Secret.
Bruk av dynamiske token ligger på Microsofts roadmap, men ingen datoer eller at det faktisk vil bli støttet er gitt, så Buypass vil som en midlertidig ordning åpnet for token som har levetid på inntil 3 måneder for de brukerstedene som bruker AD Azure.
Det at Brukerstedet ønsker å bruke «long lived bearer token» må bestilles spesielt ved etablering av oidc client for scim-api. Brukerstedet må selv sørge for å bytte access tokenet hver 3 måned og gjøre dette tilgjengelig i sin AD-konfigurasjon, dvs. sjekke hvor lenge tokenet de får er gyldig og be om et nytt token og bruke det nye isteden, før det gamle utløper.
*)
Buypass implementasjon av oauth2 og openid connect rfc bygger på konseptet om kortlevde access tokens og bruk av refresh token dersom man trenger å utvide levetiden. Dette er best practice og et aktivt sikkerhetsvalg som er gjort for å hindre ondsinnet tilgang til tjenesten.
Access token forespørres gjennom «Client Credentials Grant»: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4 og https://datatracker.ietf.org/doc/html/rfc6749#section-4.4. Her er det beskrevet at refresh token ikke skal utstedes sammen med access token, og det er derfor Buypass ikke lagt opp til at client_credetials grant skal ha mulighet for å gjøre refresh av token.
English:
AD can be implemented in one of the following three variants:
AD locally
AD hybrid - AD locally with «shadow transfer» to Azure - here local AD is the master with a copy to cloud
AD Azure
Local and hybrid AD support the use of dynamic tokens, which is what Buypass has implemented using scim-api *.
AD Azure has scim-provisioning as a built in feature, but this can by default only be set up with Secret Token which is a static password. It is possible to use AD Gallery allowing use of ClientID / Client Secret.
The use of dynamic tokens is on Microsoft's roadmap, but no dates or that such feature actually will be supported are given. Buypass will as a temporary solution open for tokens that have a lifespan of up to 3 months for the Merchants using AD Azure.
If the Merchant wants to use "long lived bearer token" this must be ordered especially when establishing the oidc client for scim-api. The Merchant must make sure to change the access token every 3 months and make this available in its AD configuration, ie check how long the token they receive is valid and ask for a new token and use the new one instead, before the old one expires.
*)
Buypass implementation of oauth2 and openid connect rfc is based on the concept of short-lived access tokens and the use of a refresh token if you need to extend the service life. This is best practice and an active security choice made to prevent malicious access to the service.
Access token is requested through «Client Credentials Grant»: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4 and https://datatracker.ietf.org/doc/html/rfc6749#section-4.4. Here it is described that the refresh token should not be issued together with the access token, and it is the reason Buypass has decided that the client_credetials grant should not have the opportunity to refresh the token.