Overview
The Identity service is an essential YaaS service. Use it to register custom identity providers for your organization.
Create and register a custom identity provider for your organization to allow your users to use YaaS with their existing accounts. With a properly configured custom identity provider in place, the YaaS OAuth2 service communicates with a remote user base to issue tokens. This allows your users to access the resources within the context of the organization for which you registered the identity provider without the need to create a new account to use with YaaS.
You can register multiple identity providers for a single organization. The custom identity provider is bound to the organization for which you register it. Using a custom identity provider, you can get tokens only for the organization you registered the custom identity provider for, as well as for all projects in that organization.
https://api.eu.yaas.io/hybris/identity/v1/.After you register a custom identity provider, you can use it in both the US and the EU regions of YaaS.
API Reference
/registration-metadata
/registration-metadata
Get the YaaS OAuth2 service configuration metadata. You must register this metadata in the identity provider to establish successful communication between the identity provider and the OAuth2 service.
/providers
/providers
Use this endpoint to fetch all identity providers registered for your organization in YaaS.
Security/Access Control: To access this method, an access token must be issued for the requested organization and have the hybris.org_manage scope.
Use this endpoint to register a new identity provider for your organization in YaaS.
Security / Access Control: To access this method, an access token must be issued for the requested organization and have the hybris.org_manage scope.
/providers/{id}
Use this endpoint to fetch information about the identity provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the organization which owns the identity provider and have the hybris.org_manage scope.
Use this endpoint to update the identity provider's information.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
Use this endpoint to delete a registered identity provider.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
Custom Identity Provider integration - available models
The Identity service allows you to register custom identity providers using two integration models: full and simplified.
In the full integration model, you must create a client for the YaaS OAuth2 service in your custom identity provider. Additionally, your custom identity provider must comply with OpenID Connect basic flow. In this model, the OAuth2 service handles every request for an access token and redirects to the identity provider's authorization endpoint to get an authorization code. The service exchanges the authorization code for an ID token. Finally, it exchanges the ID token for a valid YaaS access token.
In the simplified integration model, you must make sure that the client you create for your application in the custom identity can fetch ID tokens from the custom identity provider and then exchange such tokens for YaaS access tokens in the YaaS OAuth2 service.
Find detailed information about each integration model in the respective sections of this documentation.
Choose the right integration model
The two available custom identity provider integration models differ from each other in some key areas. Read this section to learn about the differences between the integration models and to decide which model suits your use case better.
Full integration model
To use the full integration model, the identity provider you want to use with YaaS must be OpenID Connect-compliant and implement the basic OpenID Connect flow.
In this model, the YaaS OAuth2 service handles all of the authorization steps: exchanging authorization codes for ID tokens, fetching ID tokens, and exchanging ID tokens for access tokens.
To enable this, you need to create a client in your identity provider. The OAuth2 service uses this client to interact with your identity provider. You must ensure successful communication between the client and the OAuth2 service. This is a simple operation as it only requires you to register the OAuth2 metadata you get from the /registration-metadata endpoint of the Identity service in the configuration of the client.
In the full integration model, the process of registering a custom identity provider requires you to provide more details. You must provide the token and authorization endpoints of your identity provider, as well as the JSON Web Key URI or the JSON Web Key. The OAuth2 service needs to perform all of the necessary authorization steps.
For a successful implementation of the full integration model, the YaaS OAuth2 service must be able to call the token endpoints and, if you decide to use it, the JSON Web Key Set (JWKS) URI of the identity provider. This can be impossible in some scenarios, as the network in which the identity provider resides might be inaccessible to the OAuth2 service because of the security mechanisms used.
Summary
- To use the full integration model, the custom identity provider must be OpenID Connect-compliant and implement the basic OpenID Connect flow.
- In this integration model, the client setup is remarkably easy.
- The process of registering a custom identity provider for use with the full integration model requires more details.
- The OAuth2 service must be able to call the custom identity provider's token endpoint and, if you decide to use it, the JWKS URI.
Simplified integration model
The simplified integration model works with any custom identity provider. You can use this model with custom identity providers that are not OpenID Connect-compliant. The only requirement is that the identity provider must issue valid ID tokens.
In this model, the client performs most of the steps required to authenticate the user. It calls the custom identity provider to get an ID token and then exchanges it for an access token in the OAuth2 service. Therefore, you must configure the client to contact both the custom identity provider and YaaS OAuth2 service and store two different pairs of credentials. The client must also pass the ID tokens in the id_token_hint parameter and handle two additional error types that the OAuth2 service sends. Furthermore, the client must know the location of the custom identity provider's sign-in form and use it as part of handling one of the error scenarios.
In the simplified integration model, the process of registering a custom identity provider requires a minimal amount of configuration details. You must specify the issuer of the ID tokens, as well as the JSON Web Key Set or JSON Web Key Set URI of the identity provider. If the OAuth2 service cannot access the JWKS URI of the custom identity provider, you can substitute the URI with an array of JSON Web Key objects. In such a case, it is vital to maintain up-to-date JSON Web Keys so that the OAuth2 service recognizes the ID tokens it receives from a custom identity provider as valid and not forged.
Use this integration model in scenarios where the OAuth2 service cannot reach the custom identity provider in its network. As an intermediary, the client lives outside of YaaS network, and outside of the network of the identity provider, which allows these components to communicate.
Summary
- You can use the simplified integration flow with any custom identity provider, whether it is OpenID Connect-compliant or not.
- In this integration model, the client setup requires more effort.
- The custom identity provider registration for the simplified integration model requires a minimal amount of details.
- The simplified integration model works even when the OAuth2 service and the custom identity provider cannot communicate because of the security restrictions on the networks they live in.
Choose the JSON Web Key source
The mechanism of JSON Web Key verification is vital for the security of your custom identity provider implementation. It helps to ensure that the tokens circulating between the identity provider, the clients, and the OAuth2 service are valid and not forged.
To ensure that the JWKS used in your implementation is always up-to-date and does not require manual updating, set the JSON Web Key source to a URI in the identity provider. This way, the OAuth2 service has access to the JSON Web Key directly in the identity provider. If the current key set changes in the identity provider, the OAuth2 has access to the new set without the need to reconfigure the implementation manually.
Both integration models give you the option to provide the JSON Web Key as an array of objects directly in the identity provider configuration. This is a valid solution in scenarios where the OAuth2 service cannot reach the identity provider JWKS URI for reasons such as network security restrictions. When choosing this solution, remember to maintain up-to-date JWKS in the custom identity provider.
Treat the option to provide the JSON Web Key directly in the identity provider configuration as an alternative solution for use in special circumstances.
Custom Identity Provider - full integration model
The process of registering a custom identity provider in YaaS consists of three basic steps:
Get the registration meta-data from the OAuth2 service
To get the meta-data required to register a custom identity provider in YaaS, you must call the /registration-metadata endpoint of the Identity service.
This is a sample request to the /registration-metadata endpoint. It is an open resource, which means that you don't have to include an access token when you call this endpoint.
curl -X GET "http://api.eu.yaas.io/hybris/identity/v1/registration-metadata"The response includes an array of redirectURIs and an array of postLogoutRedirectURIs. To ensure that you use up-to-date information, call the
/registration-metadata endpoint every time you register a new custom identity provider for your organization.Create a client for YaaS OAuth2 service in your identity provider and obtain the client ID and client secret
Create a new client in your custom identity provider. Use the meta-data you obtained from the/registration-metadata endpoint.Get the client ID and client secret from the newly created client. You need this information to register your custom identity provider in YaaS.
Register your custom identity provider in the Identity service
To register your custom identity provider, you must call the /providers endpoint of the Identity service. The request must include an access token issued for the organization for which you want to register the custom identity provider. The token must also include the hybris.org_manage scope.
Pass the OpenID configuration, client ID and client secret you obtained from the client you created in the previous step. Additionally, include the display name of your custom identity provider.
This is a sample identity provider registration request to the/providers endpoint. Line breaks are added for better readability.curl -X POST "http://api.eu.yaas.io/hybris/identity/v1/providers" \
-H 'Authorization: Bearer ACCESS_TOKEN_HERE \
-H 'Content-Type: application/json' \
-d '{"displayName":"My IDprovider","credentials":{"clientId":"a9883977-97e3-44d9-a4cb-7c2df0f7a267","clientSecret":"2loftph991j058u3"}, \
"openidConfiguration":{"issuer":"https://someorg.io","authorization_endpoint":"https://someorg.io/authorize", \
"token_endpoint":"https://someorg.io/token","jwks_uri":"https://someorg.io/jwks"}}' \
The successful response from the Identity service confirms the registration of the custom identity provider and returns the alpha-numeric ID of the custom identity provider, as well as a link to the registered provider. This is a sample code 201 response from the service:
{"id":"594b8c8176b391a1c5c6344a","link":"https://api.eu.yaas.io/hybris/identity/v1/providers/594b8c8176b391a1c5c6344a"}Custom Identity Provider - simplified integration model
The YaaS OAuth2 service recognizes and handles ID tokens issued by custom identity providers. This allows for a simpler integration model that does not require registering a client for the OAuth2 service in your custom identity provider.
In the simple integration model you must:
- Register the custom identity provider in YaaS.
- Create a client for your application in the custom identity provider.
- Create a client for your application in YaaS.
When you use this integration model, the client registered for your application in the custom identity provider requests an ID token directly from the custom identity provider.
The client registered for your application in YaaS exchanges this ID token for an access token by calling the YaaS OAuth2 service.
Register the custom identity provider in YaaS
In the simplified integration model, you don't need to provide the same amount of detail in your custom identity provider registration request.
Two main elements of the registration request in the simplified model are:
- displayName - the display name of your custom identity provider
- openidConfiguration:
- issuer - the issuer of the ID tokens in your custom identity provider
- jwks_uri - the JSON Web Key set URI or jwks - array of JSON Web Key objects
The request must also include an access token with the hybris.org_manage scope that is issued for the organization for which you want to register a new custom identity provider.
curl -X POST "http://api.eu.yaas.io/hybris/identity/v1/providers" \
-H 'Authorization: Bearer ACCESS_TOKEN_HERE \
-H 'Content-Type: application/json' \
-d '{"displayName":"My IDprovider", \
"openidConfiguration":{"issuer":"https://someorg.io","jwks_uri":"https://someorg.io/jwks"} \
}'
Additional requirements for clients
The clients that you register for your custom identity provider must handle these error types:
- invalid_request - the YaaS OAuth2 service returns this error when: you call the OAuth2 service using the custom identity provider configured using the simple integration model, and the call doesn't include the id_token_hint parameter with a valid ID token issued for the custom identity provider
- login_required - when the request includes an invalid or expired ID token
Scopes management
When you use a custom identity provider, you can decide where you manage the scopes assigned to the user. You can choose between managing the scopes in your custom identity provider and managing the scopes in the Builder.
Choose either of the described approaches by using the scopesGrant parameter. You can set this parameter when you create a new custom identity provider, or update the configuration of an already existing one.
The scopesGrant parameter has two properties:
- scopesSource
- claimName
The scopesSource property allows you to choose where you manage the scopes assinged to the users.
- Set the value of the property to
claimto manage the scopes in your custom identity provider. - Set the value of the property to
yaasto manage the scopes in the Builder. - If you don't set the value of this property, the Identity service automatically sets it to the default value, which is
yaas.
When you set the scopesSource to
claim, define the name of the claim in which the OAuth2 service looks for scopes assigned to the user by defining the claimName property.- If you don't set the value of this property, the service sets the claimName to the default value, which is
scope. - This property works only when you set the scopesSource to
claim.
Use the custom identity provider
After you successfully register your custom identity provider in the Identity service, you can use it with the Implicit Grant and the Authorization Code Grant authorization flows available in YaaS.
To use your custom identity provider, provide the ID you received in the code 201 successful response from the Identity service as the value of the hybris_id_provider parameter in the request to the OAuth2 service.
This example shows an Authorization Code Grant flow access token request that uses a custom identity provider registered using the full integration model:
curl -i -X GET 'https://api.eu.yaas.io/hybris/oauth2/v1/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE_NAME&state=STATE&hybris_id_provider=724987custom_idp_id09u'If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.