8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
API standards
8.1 Identity Usage
Service Group: Client Management
API to add new open ID connect (OIDC) clients, it can be invoked by other modules which manages the relying parties / partners.
Each relying party can associate to one or multiple OIDC client Ids.
On create, OIDC client status will be by default set to "active".
Valid JWT issued by a trusted IAM system with "add_oidc_client" scope.
OIDC client details
Current date and time when the request is sent
OK
Date and time when the response is generated
Unauthorized
API to update existing Open ID Connect (OIDC) client, it can be invoked by other modules which manages the relying parties / partners when there any updates on the fields accepted in this API.
Authentication and authorization is based on a valid JWT issued by a trusted IAM system including "update_oidc_client" scope.
Valid JWT issued by a trusted IAM system including "update_oidc_client" scope.
Client Identifier
785b806d0e594657b05aabdb30fff8a4Current date and time when the request is sent
OK
Date and time when the response is generated
OK
This is the authorize endpoint of Open ID Connect (OIDC). The relying party applications will do a browser redirect to this endpoint with all required details passed as query parameters.
This endpoint will respond with a HTML page / JS application to be loaded in the browser.
All the validations on the query parameter values will be performed, in case of any failures respective error message will be sent along with browser redirection back to relying party application.
Specifies what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. OpenID Connect requests MUST contain the OpenID scope value.
openid profilePossible values: The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".
Valid OAuth 2.0 Client Identifier in the Authorization Server.
Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.
String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.
ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.
Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.
consentPossible values: Maximum Authentication Age. This specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated by the OP. If the elapsed time is greater than this value, then the OP MUST attempt to actively re-authenticate the end user. The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter. When max_age is used, the ID Token returned MUST include an auth_time claim value.
End user's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.
End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
This parameter is used to request specific claims to be returned. The value is a JSON object listing the requested claims. The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON.
OK
Loads IDBB UI application in browser for interacting with user for Login process
No content
OK
Loads IDBB UI application in browser for interacting with user for Login process
No content
Once the client / relying party application receives the authorization code through redirect, this OIDC complaint endpoint will be called from the relying party backend application to get the ID Token and Access Token.
- The only supported client authentication method : private_key_jwt
- ClientAssertion is a signed JWT with client's private key, corresponding public key should be shared with IDBB during the OIDC client creation process.
- clientAssertion JWT payload must be as below:
The JWT MUST contain the following REQUIRED Claim Values and MAY contain few additional OPTIONAL Claim Values:
iss* (Issuer): This MUST contain the client_id of the OIDC / OAuth Client.
sub* (Subject): This MUST contain the client_id of the OIDC / OAuth Client.
aud* (Audience): Value that identifies the IDBB server as an intended audience. The IDBB server MUST verify that it is an intended audience for the token. The audience SHOULD be the URL of the IDBB's token endpoint.
exp* (Expiration): Time on or after which the ID token MUST NOT be accepted for processing.
iat*: Time at which the JWT was issued.
Note: The Client Assertion JWT can contain other Claims. Any Claims used that are not understood WILL be ignored.
Authorization code grant type.
Authorization code, sent as query param in the client's redirect URI.
Client Id of the OIDC client.
Type of the client assertion part of this request.
Private key signed JWT, This JWT payload structure is defined above as part of request description.
Valid client redirect_uri. Must be same as the one sent in the authorize call.
OK
Bad Request
Once the access token is received via the token endpoint, relying party backend application can call this OIDC compliant endpoint to request for the user claims.
Consented user claims will be returned as a JWT. This JWT will be a nested JWT which is signed using JWS and then encrypted using JWE.
Example: Assuming the below are the requested claims by the relying party
name : { "essential" : true }
phone: { "essential" : true }
Response 1: When consent is provided for both name and phone number:
{ "name" : "John Doe", "phone" : "033456743" }
Response 2: When consent is provided for only name:
{ "name" : "John Doe" }
Response 3: When Claims are requested with claims_locales : "en fr"
{ "name#en" : "John Doe", "name#fr" : "Jean Doe", "phone" : "033456743" }
Supported User Info Claims
Access token received from /token endpoint
OK
The response is signed and then encrypted, with the result being a Nested JWT. Signed using the IDBB's private key. Signed full JWT will then be encrypted using OIDC client's public key.
Unauthorized
This endpoint is only for facilitating the OIDC provider details in a standard way.
Reference: https://openid.net/specs/openid-connect-discovery-1_0.html
OK
URL using the https scheme with no query or fragment component that the RP asserts as its Issuer Identifier. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.
URL of the OAuth 2.0 Authorization Endpoint.
URL of the OAuth 2.0 Token Endpoint.
URL of the OP's UserInfo Endpoint.
URL of the OP's JSON Web Key Set [JWK] document.
URL of Client Registration Endpoint.
JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for.
Languages and scripts supported for values in Claims being returned.
Languages and scripts supported for the user interface.
OK
Generate link code request is raised from IDBB UI application.
- UI application creates a deeplink with this link-code as parameter.
- This deeplink is embedded in a Machine-readable-code (like QR code) and the same is rendered in the UI.
- End user scans this machine-readable-code to open wallet app.
- On open of wallet-app, wallet-app invokes /link-transaction endpoint.
- In the UI application, once machine-readable-code is rendered, at the same time /link-status endpoint is invoked as a long polling request.
CSRF token as set in cookie key 'XSRF-TOKEN'
OK
OK
The link status endpoint is invoked from IDBB UI application.
- Checks the status of link code and will return the status as LINKED once the /link-transaction endpoint is called from wallet application.
CSRF token as set in cookie key 'XSRF-TOKEN'
OK
OK
Link authorization code endpoint is invoked from UI application.
- This is a Long polling request to IDBB backend.
- validates the transactionId
- validates the linkCode if its LINKED.
- checks the cache to see if the auth-code is generated, if yes returns the response.
- If the auth-code is not yet generated, polling request waits for the configured time.
- On successful response, IDBB UI should redirect to the provided redirectUri with auth-code or error details.
CSRF token as set in cookie key 'XSRF-TOKEN'
OK
OK
The link transaction endpoint is invoked from Wallet-app.
-
Validates the link-code and its expiry and generates the linkTransactionId. This linkTransactionId is linked to transactionId used in the /link-code endpoint.
-
Returns the auth-factors, clientName, logoUrl, User claims, authorize scopes along with linkTransactionId.
Note: Wallet-app will hereafter address the transaction with this linkTransactionId for the /authenticate and /consent endpoints.
OK
OK
Once end user provides the user identifier (UIN/VID) and all the required auth challenge to the Wallet-app, this endpoint will be invoked from wallet-app.
Supported auth-challenge depends on the integrated IDBB implementation.
- Validates linkedTransactionId.
- Validates null / empty individualId.
On Authentication Success: Only linkTransactionId is returned in the below response without any errors.
On Authentication Failure: Error list will be returned.
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'OK
OK
Once the authentication is successful and user permission is obtained, this endpoint will be invoked by the wallet app to send the accepted user claims and permitted scopes.
- Validates linkedTransactionId.
- Validate accepted claims and permitted scopes in the request.
- If valid, stores the accepted claims and permitted scopes in the datastore.
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'OK
OK
Wallet binding endpoint is invoked by Wallet's backend server.
- Action will be initiated from wallet-app with authChallenge by user.
- Wallet backend server will receive the authChallenge, create this request and send to IDBB to complete the binding process.
- Binded walletUserId (WUID) is returned with IDBB signed certificate.
Note: Binding entry uniqueness is combination of these 3 values -> (PSUT, public-key, auth-factor-type)
Valid JWT issued by a trusted IAM system with "wallet_binding" scope.
An identifier for the partner.
An API key provided to the partner for authentication purposes.
OK
OK
8.2 Identity Management
8.3 Credential Management
8.4 Subscription Management
8.5 Administration Management
Last updated
Was this helpful?