Welcome to next-doc-portal!

Authentication with OAuth 2.0

PPaaS supports the industry-standard authorization protocol OAuth 2.0. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to a protected resource on behalf of a resource owner or on its own behalf.

The URL provided on this page is set for the demo environment, for more information about the URL in the production environment, refer to the table Environment and portal.

OAuth 2.0 endpoints

PPaaS OAuth 2.0 API exposes two endpoints:

Authorization endpoint

The OAuth 2.0 API supports the authorization code grant type. For this specific grant, authenticate the resource owner from a browser and then request an access token from the PPaaS authorization server.

To authenticate the resource owner, call the oauth2 API POST /oauth2/v1/{userDomainId}/auth. Here, userDomainId is the user domain of your organization.

Access token endpoint

An access token is issued to your application with the approval of the resource owner. Your application uses the access token on behalf of the resource owner or on its own behalf, to access protected resources in PPaaS. The access is according to the user's or the application's access rights.

To get an access token, call the oauth2 API POST /oauth2/v1/{userDomainId}/token. Here, userDomainId is the user domain of your organization.

The x-www-form-url encoded request body requests an access token.

OAuth 2.0 has specified different flows named grant types to get an access token. The x-www-form-url parameters provided in the request body depend on the grant type.

OAuth 2.0 API supported grant types

OAuth 2.0 API supports the following grant types:

Authorization code
Resource owner password credentials
Client credentials
Refresh token

PPaaS supports the following authorization flows:

Authorization code
Client credentials

Authorization code

The authorization code flow is used to authenticate single-page applications or regular web applications.

To authenticate the resource owner, call the oauth2 API POST https://auth.demo.ppaas.tech/oauth2/v1/{userDomainId}/auth. Here, userDomainId is the user domain of your organization.

Request

Provide the following path parameters in the request:

client_id: Client ID of the application that requests to authenticate the resource owner.
client_secret: If relevant, the client secret of the application that requests to authenticate the resource owner.
redirect_uri: Callback to redirect the user after successful login. This redirection URL must be previously registered for this client_id when the application is created on the PPaaS Direct Client portal.
scope: Open ID scope. If not present, the default value is profile email.
state: An opaque value that will be returned in the callback, mainly to avoid a cross-site request forgery (CSRF) attack. It is recommended to set this value and check it in the callback.
response_type: To request authorization code flow, set the value to code.

Response

When the resource owner grants access, the PPaaS authorization server redirects the user agent to your application callback with a code value and a state value. Your application should verify that the state callback is the same as the one passed in the authorization request.

The authorization code is used once to get tokens by calling the token endpoint.

Here is an example of a redirect call after successful authentication:

https://mycompany.portal.ppaas.com/my_callback?code=7f75367e7881255134e1375e723d1dea8ad5f6a4fdb79d938df1f1754a830606&state=bf182471-3c22-4386-8859-49a0a17a3790.

If the PPaaS authorization server fails to authenticate the resource owner or the resource owner denies access, the user agent is redirected to your application callback. The callback includes the HTTP error code sent by the authorization server and the state.

An example of a redirect call after a failed authentication is:

https://mycompany.portal.ppaas.com/my_callback?error=400&state=bf182471-3c22-4386-8859-49a0a17a3790.

The error parameter contains the HTTP error code.

Access token

An access token is issued to your application with the approval of the resource owner. Your application uses the access token on behalf of the resource owner or on its own behalf to access protected resources in PPaaS. The access is according to the user's or the application's access rights. OAuth 2.0 has different flows named grant types to get an access token.

To get an access token, call the oAuth2 API. Provide the following parameters in the request body of the oauth2 endpoint POST https://auth.demo.ppaas.tech/oauth2/v1/{userDomainId}/token:

grant_type: The grant type specifies the access token type of the request. Set this to authorization_code.
client_id: Client ID of the application that requests to authenticate the resource owner.
client_secret: If relevant, the client secret of the application that requests to authenticate the resource owner.
code: The authorization code received from the server after successful authentication via the callback.

Sample code using the cURL command line tool

curl

curl -X POST https://auth.demo.ppaas.tech/oauth2/v1/{userDomainId}/token -H 'accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code&client_id=my_application&client_secret=aea4a35bf-beba-42be-a9d9-31610c7a04ba&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &code=5eb607a6df306b8da0834230e8d0196499cd7c9bdb085f330c63113655afb19c'

Refresh token

The refresh token flow is used to refresh a token obtained with the Authorization code flow or Resource owner password credentials flow.

Provide the following parameters in the request body of the oauth2 endpoint POST /oauth2/v1/{userDomainId}/token:

grant_type: The grant type specifies the access token type of the request. Set this to refresh_token.
client_id: Client ID of the application that requests to authenticate the resource owner.
client_secret: If relevant, the client secret of the application that requests to authenticate the resource owner.
refresh_token: The refresh token is issued to the application.
scope: Can be used to override the scope originally granted by the resource owner. The requested scope must not include additional scopes that were not issued with the original access token. If omitted, it is treated as equal to the scope originally granted by the resource owner.

Here is a sample code using the cURL command line tool.

curl

curl -X POST https://auth.ppaas.com/oauth2/v1/my_userDomain/token -H 'accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=refresh_token&client_id=my_application&client_secret=aea4a35bf-beba-42be-a9d9-31610c7a04ba&refresh_token='

json

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJodHRwczovL2F1dGgucHBhYXMuY29tL2F1dGgvcmVhbG1zL2V4YW1wbGUiLCJpYXQiOjE2MzgxODE2NDksImV4cCI6MTY2OTcxNzY0OSwiYXVkIjoibXlfYXBwbGljYXRpb24iLCJzdWIiOiJjZjU0YjI5NC0xYmZiLTQ1MWQtOGQyYS0wODAwMzYzMzQyOWYiLCJ0eXAiOiJCZWFyZXIiLCJnaXZlbl9uYW1lIjoiSm9obiIsImZhbWlseV9uYW1lIjoiRGFvIiwiZW1haWwiOiJqb2huLmRhb0BleGFtcGxlLmNvbSIsIlBlcm1pc3Npb25zIjpbImNhdC5tUGtnLmFkZCIsImNhdC5wcmMuYWRkIl0sImxvY2FsZSI6ImZyLUZSIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwidXNlcm5hbWUiOiJqZGFvIn0.wAOj7mtEMZ0DrdsQoT9OZIJ0djETOJESVnJNQYFkMd9KazCVQfa-BNhT7ypu99wGsxFeJT3pdNfifN8h1uFlAQ",
    "expires_in": 600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 1609968533,
    "scope": "email profile",
    "refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJodHRwczovL2F1dGgucHBhYXMuY29tL2F1dGgvcmVhbG1zL2V4YW1wbGUiLCJpYXQiOjE2MzgxODE2NDksImV4cCI6MTY2OTcxNzY0OSwiYXVkIjoibXlfYXBwbGljYXRpb24iLCJzdWIiOiJjZjU0YjI5NC0xYmZiLTQ1MWQtOGQyYS0wODAwMzYzMzQyOWYiLCJ0eXAiOiJSZWZyZXNoIiwiZW1haWwiOiJqb2huLmRhb0BleGFtcGxlLmNvbSIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.1OpCqA5jhyD5uDkWmsyp1Z5Ad35Rk4xDhpwNLg-Bxm8M_GlrdcCCpa0MgO9Wg32wmkL6Y-XJXSf_2Vrgq878JA"
}

The response contains the following attributes:

access_token: The user access token issued to the application.
expires_in: The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire within one hour from the time the response was generated.
refresh_token: The refresh token is issued to the application. Access tokens have a limited lifetime. If your application needs access to the PPaaS API beyond the lifetime of a single access token, a new access token can be obtained using the refresh token grant type.

Use your access token in an API call

Your application can call a subscribed PPaaS API with the access token set in an HTTP authorization header.

Sample code using the cURL command line tool:

curl

curl -X GET https://auth.ppaas.com/my_api -H 'accept: */*' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJodHRwczovL2F1dGgucHBhYXMuY29tL2F1dGgvcmVhbG1zL2V4YW1wbGUiLCJpYXQiOjE2MzgxODE2NDksImV4cCI6MTY2OTcxNzY0OSwiYXVkIjoibXlfYXBwbGljYXRpb24iLCJzdWIiOiJjZjU0YjI5NC0xYmZiLTQ1MWQtOGQyYS0wODAwMzYzMzQyOWYiLCJ0eXAiOiJCZWFyZXIiLCJnaXZlbl9uYW1lIjoiSm9obiIsImZhbWlseV9uYW1lIjoiRGFvIiwiZW1haWwiOiJqb2huLmRhb0BleGFtcGxlLmNvbSIsIlBlcm1pc3Npb25zIjpbImNhdC5tUGtnLmFkZCIsImNhdC5wcmMuYWRkIl0sImxvY2FsZSI6ImZyLUZSIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwidXNlcm5hbWUiOiJqZGFvIn0.wAOj7mtEMZ0DrdsQoT9OZIJ0djETOJESVnJNQYFkMd9KazCVQfa-BNhT7ypu99wGsxFeJT3pdNfifN8h1uFlAQ'

JSON Web Token details

Registered claims

The following claim names are registered in the IANA JSON Web Token Claims. These claims will always be present in the token payload generated by the identity provider.

Claim name	Type	Description
aud	string	This claim identifies the recipient that this token is intended for. REQUIRED. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the relying party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is only one audience, the aud value MAY be a single case-sensitive string.
sub	string	This claim identifies the principal that is the subject of the token. For key cloak, the sub is a random UUID containing the unique ID of the user across the realm.
jti	string	This claim identifies the JWT ID, random UUID containing the unique identifier of the token.
azp	string	This claim identifies Authorized party - the party to which the ID token was issued.
exp	number	This claim defines the expiration time of the token. The token is valid if the current date/time is before the `exp` date/time value. Its value represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
nbf	number	This claim defines the `not valid before` date/time, the time before which the token must not be accepted for processing. Its value represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
iat	number	This claim defines the `issued at` time. The time at which the claim was issued. Its value represents the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
iss	string	This claim identifies the issuer that has issued the token. The claim value contains the URL of the identity provider (i.e., realm URL).

Other Claims

Custom claims

OIDC scope: profile

Claim name	Type	Description
user_domain	string	This claim contains the name of the user domain of the organization to which the end-user is attached. Example of organization is a merchant aggregator. For PPaaS, tenant, merchant aggregators, or DFO organizations, the user domain name is the name of the organization. The user domain is also named realm name.
groups	JSON	This claim contains the list of groups that the user belongs to.
entityId	string	The entity of the user. For a merchant, the entityId contains the unique identifier of the merchant. For a tenant user, it contains the Tenant Id.
um_scope	JSON	The `um_scope` contains a list of entityId and entityType elements. The entityId contains the entity identifier for which this user has access rights. The entity type defines the entry type (tenant, merchant aggregator, merchant). Example: A tenant user can have access rights to a given number of merchant organizations in addition to its own organization.
permissions	JSON	This claim contains the list of permissions assigned to this user. These permissions allow the user to have access to resources protected by PPaaS services.

Authentication

The authentication fields give information on how the user was authenticated and, on the device that was used for authentication.

OIDC scope: auth

Claim name	Public device	Unattended device or Axon devices	Confidential Device	External machine
`device description`	Web browser, mobile phone, or other public device	Confidential device well known by the taxonomy library	Confidential device well known by the taxonomy library	For M2M connection
`device_type`	`public`	The type of the device given by the taxonomy library	The type of the device given by the taxonomy library	`m2m`
`device_id`	`unknown`	The identifier given by the taxonomy library	The identifier given by the taxonomy library	`unknown`
`method`	`web`, `api`, or `device_flow`	`implicit`	`api` or `device_flow`	`api`
`2fa`	`none` or `otp`	`none`	`tls`	`none`
"cnf":{"x5t#S256": "..."}	not present	The value of the HTTP header `X-SSL-Client-S256` used for the creation of the token	The value of the HTTP header `X-SSL-Client-S256` used for the creation of the token	not present

User Info

The applications use the user info fields to obtain the end-user's details such as name, email, and time zone.

OIDC scope: profile

Claim name	Type	Description
name	string	Full name of the end-user
given_name	string	Given name or first name of the end-user
family_name	string	Surname name or last name of the end-user
preferred_username	string	Preferred name or shortened name of the end-user. For Keycloak, this claim contains the username (login)
zoneinfo	string	End-user's time zone. Example: Europe/Paris
locale	string	This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash. For example, en-US or fr-CA.
datetimeformat	string	This claim defines the date/time iso-8601 format. This format is used to display the end-user's current date/time. Example: yyyy-MM-dd hh:mm:ss

OIDC scope: email

Claim name	Type	Description
email	string	End-user's email address
email_verified	boolean	The status of end-user email verification. This field is set to true if the email has been verified, so it must be true since the token is not generated if the email is not verified

OIDC scope: phone

Claim name	Type	Description
phone_number	string	End-user's preferred telephone number. E.164 is RECOMMENDED as the format of this claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 extension syntax, for example, +1 (604) 555-1234;ext=5678
phone_number_verified	boolean	The status of the end-user's phone number is available for verification. This field is true if the phone number has been verified

OIDC scope: address

Claim name	Type	Description
address	JSON Object	End-user's postal address in JSON format. Members of this JSON object are defined by the Openid connect specification

Requesting claims using scope values

For OpenID connect, the scope can be used to request that specific sets of information be made available as claim values in the token payload. Openid connect has defined the following scope: profile, email, phone, and address. Each scope allows for the retrieval of the set of claim values defined above. If the scope is not present in the auth request, the default scope is used: Openid profile email.

Below is an example of an authentication request with explicit scope.

text

https://indx.com/auth/login?
&domain=your_realm_domain_name
&callback=https://your_app.com/callback
&scope=openid profile email phone

JWT sample

json

{
    "typ": "JWT",
    "alg": "HS256",
    "kid": "mokup-key"
}

Sample token payload:

json

{
    "iss": "http://indx.ingenico.com/auth/realms/orgdemo",
    "iat": 1606816114,
    "exp": 1638352114,
    "aud": "www.indx.ingenico.com",
    "sub": "dce1d487-4331-42c0-ab25-9ca81b987cd4",
    "nbf": "0",
    "jti": "06b6465c-44f7-4cf4-883c-56a55ab850cc",
    "family_name": "Dupond",
    "given_name": "Alfred",
    "email": "alfred.dupond@xyz.com",
    "locale": "fr-FR",
    "groups": [
        "INDX Aggregator Service",
        "MerchantA-admin"
    ],
    "entityId": "5fd7c4fc-c8cb-4cba-b68f-90b20e79fd2b",
    "user_domain": "dev-tenant-onboarding",
    "permissions": [
         "Admin.PPaaS.Package.Delete",
         "Admin.PPaaS.Package.Edit",
         "onb.directClientDelete",
         "onb.directClientRead",
         "onb.directClientWrite",
         "prov.devStockRead",
         "prov.logDevRead",
         "prov.merchantRead",
         "prov.orgRead",
         "prov.physDevRead",
         "prov.storeRead",
         "rep.transactionRead",
         "rep.transactionWrite"
    ],
    "cnf": {
      "x5t#S256": "71dda5b3ce56a79f9c711ed4019ebf2ca08877e3029b0eaea1a30f97d76b4cef"
    }
    "name": "Alfred Dupond",
    "preferred_username": "adupond",
    "um_scope": {
         "entityId": "5fd7c4fc-c8cb-4cba-b68f-90b20e79fd2b",
         "entityType": "tenant"
    },
    "locale": "fr-FR",
    "datetimeformat": "yyyy-MM-dd hh:mm:ss",
    "zoneinfo": "Europe/Paris"
    "device_type": "public",
    "device_id": "unknown",
    "method": "web",
    "2fa": "otp",
    "scope": "email profile auth"
}

Signature Key (HS256, 128 bit key). When used with the selected IDP, the signature also should be ECC 256.

text

yvWSszbNKrWGiCkI9gXJW409PZ2pesXu3Qx84ntgLmSW86kb0EPbnBQBXZfmTIx1IaJdzhwdvM3sesNopQdgfJHJXWl1BrD6IcKhJC43M3xXydIyDxc9vhL5fHuEE5ed

Token encoded in base-64:

text

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vaW5keC5pbmdlbmljby5jb20vYXV0aC9yZWFsbXMvb3JnZGVtbyIsImlhdCI6MTYwNjgxNjEx
NCwiZXhwIjoxNjM4MzUyMTE0LCJhdWQiOiJ3d3cuaW5keC5pbmdlbmljby5jb20iLCJzdWIiOiJkY2UxZDQ4Ny00MzMxLTQyYzAtYWIyNS05Y2E4MWI5ODdjZDQiLCJuY
mYiOiIwIiwianRpIjoiMDZiNjQ2NWMtNDRmNy00Y2Y0LTg4M2MtNTZhNTVhYjg1MGNjIiwiZmFtaWx5X25hbWUiOiJEdXBvbmQiLCJnaXZlbl9uYW1lIjoiQWxmcmVkIiwiZW1haWwiOiJhbGZyZWQuZHVwb25kQHh5ei5jb20iLCJsb2NhbGUiOiJmci1GUiIsImdyb3VwcyI6WyJJTkRYIEFnZ3JlZ2F0b3IgU2VydmljZSIsIk1lcmNoYW50QS1
hZG1pbiJdLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJBbGZyZWQgRHVwb25kIiwiZGV2aWNlX3R5cGUiOiJwdWJsaWMiLCJkZXZpY2VfaWQiOiJ1bmtub3duIiwibWV0aG9k
Ijoid2ViIiwiMmZhIjoib3RwIiwic2NvcGUiOiJlbWFpbCBwcm9maWxlIGF1dGgifQ.VeIQW5pFd3aCI4vP9E_P5HeGXnGj8BClIID7IIveoUc