The OIDC/OAuth2 authentication using service account

Overview

This article describes OIDC/OAuth2 authentication using a service account. The access token for a service account can be created w/i or w/o tenant context. The tenant context determines the tenant (e.g. customer) for following REST API requests. The non-tenant access can be used in rare cases when no tenant context is required.

Learn more about OpenID Connect specifications.

How to obtain clientId and clientSecret

1. Use Product App or DevOps App to register your application
2. Use Application agent catalogue in Integration section to get clientId and reset secrets

OIDC IdentityProvider API endpoints

IdentityProvider API base URL: https://{hostname}/api/asol/idp

1. Get OIDC configuration via discovery endpoint
   GET /.well-known/openid-configuration

• anonymous endpoint
• sample response (shortened):

{
  "issuer":"https://demo.avaplace.com/api/asol/idp",
  "token_endpoint":"https://demo.avaplace.com/api/asol/idp/connect/token",
  ...
  "scopes_supported":["openid",...,"apiim",...],
  "grant_types_supported":[...,"client_credentials",...],
  ...
}

2. Obtain JWT access token for service account
   POST /connect/token

• note: use discovery endpoint to get the URL of token endpoint
• basic authentication using base64-encoded clientId:clientSecret string
• request headers:
  • Content-Type: "application/x-www-form-urlencoded"
  • Authorization: "Basic cGxhemEt...wYTAyNDM="
• request body properties:
  • grant_type - (mandatory) the requested authentication grant type
  • tid - the requested tenant identifier, required for access to specified tenant
  • scope - (optional) the requested scope
• sample request body:

{
  "grant_type": "client_credentials",
  "tid": "ASOLEU-DEV-fd9ad6b9-2f29-4c7a-9a3a-c7469e19b1ff",
  "scope": ""
}

• sample response:

{
  "access_token": "eyJhbGc...ueumCA",
  "expires_in": 600,
  "token_type": "Bearer",
  "scope": "apiim"
}

Note: use token_type and access_token in authorization header for following API calls.

The authenticated access to REST API

1. Get response from "My/Example" endpoint using REST API
   GET /api/v1/my/example

• note: use access token to authenticate http requests
• OAuth2 authentication using JWT access token
• request headers:
  • Authorization: "Bearer eyJhbGc...ueumCA"

Useful IdentityProvider API endpoints

IdentityProvider API base URL: https://{hostname}/api/asol/idp

Get available tenants and mandants

GET /api/v2/Tenants

• offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
• sample response (shortened):

{
  "totalCount": 3,
  "items": [
    {
      "identifiers": [],
      "organizations": [
        {
          "id": "fff2d400-9838-4513-9c7b-535a03bd8c94",
          "name": "Asseco Solutions, a.s.",
          "code": "64949541|CZ",
          "organizationIdentification": {
            "number": "64949541",
            "countryCode": "CZ"
          },
          "isTenantOwner": true
        },
        {
          "id": "84f89a04-9d00-463c-a3f2-ba7310e570b5",
          "name": "TestORG",
          "code": "F9876541|CZ",
          "organizationIdentification": {
            "number": "F9876541",
            "countryCode": "CZ"
          },
          "isTenantOwner": false
        },
        ...
      ],
      "status": "Active",
      "parentTenantId": "ASOLEU",
      "parentTenantName": "Asseco Solutions, a.s.",
      "customData": {
        "erpLicense": null
      },
      "name": "ASOLEU-DEV",
      "id": "ASOLEU-DEV-fd9ad6b9-2f29-4c7a-9a3a-c7469e19b1ff"
    },
    ...
  ]
}

Get tenant info and available mandants

GET /api/v2/Tenants/{id}

• id - the requested tenant identifier
• sample response (shortened):

{
  "identifiers": [
    {
      "identifier": "@test.assecosol.com",
      "id": "cc875ed1-9777-4e1b-9228-44907681a787"
    }
  ],
  "organizations": [
    {
        "id": "fff2d400-9838-4513-9c7b-535a03bd8c94",
        "name": "Asseco Solutions, a.s.",
        "code": "64949541|CZ",
        "organizationIdentification": {
        "number": "64949541",
        "countryCode": "CZ"
        },
        "isTenantOwner": true
    },
    {
        "id": "84f89a04-9d00-463c-a3f2-ba7310e570b5",
        "name": "TestORG",
        "code": "F9876541|CZ",
        "organizationIdentification": {
        "number": "F9876541",
        "countryCode": "CZ"
        },
        "isTenantOwner": false
    },
    ...
  ],
  "status": "Active",
  "parentTenantId": "ASOLEU",
  "parentTenantName": "Asseco Solution a.s.",
  "customData": {
    "erpLicense": null
  },
  "name": "ASOLEU-DEV",
  "id": "ASOLEU-DEV-fd9ad6b9-2f29-4c7a-9a3a-c7469e19b1ff"
}