Mmadu Identity Provider Documentation

Table of Contents

1. Overview

Mmadu Identity is an authorization server used to grant authorizations to clients of an application. Authorization Servers make it possible for a resource owner delegate authorization to clients. Mmadu Identity aims to support most authorization standards like Oauth 2.0 and OIDC.

2. Features

  1. Authorization Grant Type Flow

  2. Client Credentials Grant Type Flow

  3. Jwt Token Generation

  4. Implicit Flow

3. Key Concepts

3.1. Oauth 2.0

Oauth 2.0 is a popular authorization framework for creating interoperable and secure services. To know more about this visit the Oauth 2.0 Website.

3.2. Resources and Scopes

Resources represent API’s that another service can utilize. Resources are usually secured and restrict access to users with specific authorities.

Scopes are a set of authorities that are granted to the client by the user. These authorities are enforced by the resource servers. Users delegate authorities to clients in the form of scopes.

3.3. Clients and Authorization

A client can be a user interface or another service that wants to consume a resource. In order to consume a protected resource, that client has to obtain an authorization. There are different ways by which a client can obtain an authorization and these ways are defined in authorization standards such as Oauth 2.0 and OIDC. Propietary ways of obtaining authorization can also be possible but this makes systems not interoperable with other third party systems.

Oauth 2.0 provides four basic ways of obtaining an authorization:

  1. Authorization Code Grant Type

  2. Implicit Grant Type

  3. Client Credentials Grant Type

  4. Resource Owner Credentials.

All these can be found in the Oauth 2.0 specification.

Third party (or first party) users of a service consume a service with client credentials. A Client represents details of an application or a company. This Client can have several ClientInstance objects. a ClientInstance object is analogous to the Oauth 2 client. This holds credentials and declares a specified and agreed way of accessing authorization apis.

Based on the Oauth 2.0 specification, ClientInstances can be PUBLIC or CONFIDENTIAL. This states how authentication should be handled. PUBLIC clients are not authenticated when they access client apis, while authentication is required for CONFIDENTIAL clients.

Settings like token expiry or type and allowed grant types can be configured on the ClientInstance. See [_creating_a_client_instance].

4. Default Configuration

4.1. Default Port

Mmadu Registration Service listens to port 15553 by default and this can be configured using the SERVER_PORT environment variable or the server.port SpringBoot property.

4.2. Admin Client Credentials

A default admin client is created at start up with the client identifier and secret gotten from the environment variables MMADU_ADMIN_CLIENT and MMADU_ADMIN_SECRET, or the configuration properties mmadu.admin.client and mmadu.admin.secret. The defaults are as follows:

  • Default Admin Client Identifier - mmadu_admin

  • Default Admin Client Secret - 1234567890

5. Managing Domains

You can integrate a domain to an identity provider by setting up that domain. The Mmadu Identity service provides a one step configuration for setting up a domain.

5.1. Configuring an Identity Provider for a Domain

A POST /admin/domains api call to the domain setup api will configure all entities needed to provision an authorization server for a domain.

Authority: domain_identity.initialize

5.1.1. Identity Setup Request Body Fields

Path Type Description

[].domainId

Number

Domain id

[].authorizationCodeType

String

Authorization Code Type e.g {alphanumeric, jwt}

[].authorizationCodeTTLSeconds

Number

Authorization code validity period

[].maxAuthorizationTTLSeconds

Number

Maximum validity period for every authorization

[].authorizationCodeTypeProperties

Object

Properties of the authorization code

[].refreshTokenEnabled

Boolean

Generate refresh token for refresh token enabled grants

[].refreshTokenProperties

Object

Properties of the refresh token

[].accessTokenProvider

String

Provider for generating access token e.g (jwt)

[].accessTokenProperties

Object

Access token properties

[].issuerId

String

Issuer id. Will be the used as the iss field in jwt tokens

[].clients

Array

List of predefined clients

[].clientInstances

Array

List of predefined client instances

[].resources

Array

List of predefined resources

[].scopes

Array

List of predefined scopes

5.1.2. Sample Identity Setup Request

POST /admin/domains HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmRvbWFpbl9pZGVudGl0eS5pbml0aWFsaXplIiwiZXhwIjoxNTk0NDQ3MTE3LCJpYXQiOjE1OTQ0NDcxMTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.HI5DP8hsacl9skOANt-SObMA2wTd0XcqOcn4-g_knrc5fgNycSFEO2iD5mblsWlvD-HY810iGz9SJyCEHcAdvWmq0ZUNtVDcMxDZWcjMe7vjbUbWViy7eE6TljIhF4Jqflv_8lM0SbhgC8pJQRQjjhsLT85waOLk5jVdE11rz8F4cnwywMu6hM6zMvl3yzl5d3CT-6APGr6YgN8YvMW-agAIH8xA9h1wqgpRDSIXAy5t-5tyaexd3g80iSoF0IY6_06-bOTJzQF7v3p21d6ojgUTP0k8aHxgMrKHUSLDfRWY9lWtL83udL7P8YGd87Tknpg_X4pgVw9vdeERuSFn5A
Content-Length: 1555
Host: localhost:8080

[
  {
    "domainId": 1212,
    "authorizationCodeType": "alphanumeric",
    "authorizationCodeTTLSeconds": 600,
    "maxAuthorizationTTLSeconds": 3600,
    "authorizationCodeTypeProperties": {},
    "refreshTokenEnabled": true,
    "refreshTokenProperties": {},
    "accessTokenProvider": "jwt",
    "accessTokenProperties": {
      "credentialId": {
        "type": "rsa"
      }
    },
    "issuerId": "mmadu.com",
    "clients": [
      {
        "name": "mmadu",
        "code": 1111,
        "applicationUrl": "http://localhost:18000",
        "logoUrl": "http://logo.com/logo.png",
        "tags": [
          "primary",
          "test"
        ]
      }
    ],
    "clientInstances": [
      {
        "clientCode": 1111,
        "clientType": "CONFIDENTIAL",
        "clientProfile": "web_app",
        "credentials": {
          "type": "secret",
          "secret": "1234567890"
        },
        "identifier": "mmadu-admin",
        "tlsEnabled": true,
        "supportedGrantTypes": [
          "authorization_code",
          "client_credentials"
        ]
      }
    ],
    "resources": [
      {
        "identifier": "user-management-service",
        "name": "User Management Service",
        "description": "User Management Service for Mmadu"
      }
    ],
    "scopes": [
      {
        "code": "admin",
        "name": "admin",
        "description": "Admin Privileges",
        "authorities": [
          "a.*.**",
          "r.*.**"
        ]
      }
    ]
  }
]

5.1.3. Sample Identity Setup Response

The server responds with a HTTP 204 CREATED response.

In addition to one time setup, we have individual apis for configuring and creating different entities.

5.2. Creating a Domain Configuration

A domain configuration contains settings on how to properly manage authorization on your domain. A domain can be configured by creating a domain configuration object. A POST /admin/repo/domainIdentityConfigurations will create a domain configuration.

Authority: identity_config.create

5.2.1. Domain Configuration Creation Request Fields

Path Type Description

id

string

Domain Identity Configuration ID

domainId

String

The Domain Id

authorizationCodeType

String

The format of authorization code generated in authorization_code grant type flow

authorizationCodeTypeProperties

Object

Properties for customizing the authorization code generation

authorizationCodeTTLSeconds

Number

Validity of the authorization code in seconds

maxAuthorizationTTLSeconds

Number

Maximum validity of Granted Authorization in seconds (regardless of any authorization type)

refreshTokenEnabled

Boolean

If enabled, refresh token will be issued if the flow supports it.

accessTokenProvider

String

The provider used for generating access tokens

accessTokenProperties

Object

Properties for customizing the access token generation

refreshTokenProvider

String

The provider used for generating refresh tokens

refreshTokenProperties

Object

Properties for customizing the refresh token generation

issuerId

String

issuer id of the domain

5.2.2. Sample Domain Configuration Creation Request

POST /admin/repo/domainIdentityConfigurations HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5pZGVudGl0eV9jb25maWcuY3JlYXRlIiwiZXhwIjoxNTk0NDQ3MTM3LCJpYXQiOjE1OTQ0NDcxMzIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.b03ulPg5nzqMfWSXaratExu3e-hWJPqS8ptn5iatEI-WPzY5kelUvqu1gqgbWkmWQnVr0IYAWTIX3ER6wgqepLt9ePbhy-92V9i9u56wwdXwuExxZFkfCS39gRZJsrhe1rWx-uTltmbQYdF9fFUZ4ipv7OOhSNW5dfPblU8wsYRYRGbgP7cVtSOM4HqYJ9wyLhDv6ezCJ77lahXvIBZc7QabYvHL18DuEN2MhrAK3014h4-kBj-aNVvcVwYuE4i1wBrn-NRV1FrcspFPBFAm7TU5T9UkKKS-hyiaLMn5zSp4sujTcvEBrTUf8AIsDOo3huQ2Uscynj2HjnlBkXAdsA
Content-Length: 403
Host: localhost:8080

{
  "domainId" : "1",
  "authorizationCodeType" : "alphanumeric",
  "authorizationCodeTTLSeconds" : 600,
  "maxAuthorizationTTLSeconds" : 86400,
  "refreshTokenEnabled" : true,
  "accessTokenProvider" : "jwt",
  "refreshTokenProvider" : "alphanumeric",
  "issuerId" : "mmadu.com",
  "authorizationCodeTypeProperties" : { },
  "accessTokenProperties" : { },
  "refreshTokenProperties" : { }
}

5.2.3. Sample Domain Configuration Creation Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aeb
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

5.3. Retrieving a Domain Configuration by ID

A GET request will retrieve a domain configuration by id.

Authority: identity_config.read

5.3.1. Sample Retrieve Domain Configuration by ID

GET /admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aed HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmlkZW50aXR5X2NvbmZpZy5yZWFkIiwiZXhwIjoxNTk0NDQ3MTM3LCJpYXQiOjE1OTQ0NDcxMzIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.fsoOIpIik4HcXdPkRFWZOl7JP2ULG-P2Dcm4syrRsSJJnoyEodiEzzUmbrKtzFDuYImJPVM1CFwVEGZJcpE6Ox6WP4tVbCcYyO7eF8sryZz7HyCIzOrZ628g4jf_YlDZn0KNHcnOETwi5b9WvTgauOg3Fq3C5v_WFW7Z0QmKSV66sP9Ww3gXGAqqA1757Tk21OevBA7T_JotohSuf3LDy2Tt8hhlZ1YhioiJpQZQYKFo9OE09aFYZfTPZj0sEp2Cj3I75JJTiglzbJw-FpRjTG1JpcnoJmJxZVDjOZ3ZH3WlEEzA7YwSKU63PurNz9ft9D_ZoytRNXIu9WUu9NeCnA
Host: localhost:8080

5.3.2. Retrieve Domain Configuration By ID Path Parameters

Table 1. /admin/repo/domainIdentityConfigurations/{domainIdentityConfigurationId}
Parameter Description

domainIdentityConfigurationId

The domain identity configuration id

5.3.3. Sample Retrieve Domain Configuration By ID Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 743

{
  "id" : "5f09551cea78f80ca7c29aed",
  "domainId" : "1",
  "authorizationCodeType" : "alphanumeric",
  "authorizationCodeTypeProperties" : { },
  "authorizationCodeTTLSeconds" : 600,
  "maxAuthorizationTTLSeconds" : 86400,
  "refreshTokenEnabled" : true,
  "accessTokenProvider" : "jwt",
  "accessTokenProperties" : { },
  "refreshTokenProvider" : "alphanumeric",
  "refreshTokenProperties" : { },
  "issuerId" : "mmadu.com",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aed"
    },
    "domainIdentityConfiguration" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aed"
    }
  }
}

5.3.4. Retrieve Domain Configuration By ID Response Fields

Path Type Description

id

string

Domain Identity Configuration ID

domainId

String

The Domain Id

authorizationCodeType

String

The format of authorization code generated in authorization_code grant type flow

authorizationCodeTypeProperties

Object

Properties for customizing the authorization code generation

authorizationCodeTTLSeconds

Number

Validity of the authorization code in seconds

maxAuthorizationTTLSeconds

Number

Maximum validity of Granted Authorization in seconds (regardless of any authorization type)

refreshTokenEnabled

Boolean

If enabled, refresh token will be issued if the flow supports it.

accessTokenProvider

String

The provider used for generating access tokens

accessTokenProperties

Object

Properties for customizing the access token generation

refreshTokenProvider

String

The provider used for generating refresh tokens

refreshTokenProperties

Object

Properties for customizing the refresh token generation

issuerId

String

issuer id of the domain

5.4. Retrieving a Domain Configuration by Domain ID

A GET request will retrieve a domain configuration by id.

Authority: identity_config.read

5.4.1. Sample Retrieve Domain Configuration by Domain ID

GET /admin/repo/domainIdentityConfigurations/search/findByDomainId?domainId=1 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5pZGVudGl0eV9jb25maWcucmVhZCIsImV4cCI6MTU5NDQ0NzEzOCwiaWF0IjoxNTk0NDQ3MTMzLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.a2L1j_2xF6DENOho5UAjmRrFx03OStVpEZkj1eVY7lzBwDSdf11Gfw9xq9P_NGLrBBekCD81Jk46myknpaSQ00nl28URhC2kK7UWaD0uwcyWpokGytdR8O9lyhGuVwSQAL2KvyBwGr9w4e_eneipV2e80Wt7iaUUcnGo-zqSdmZlRcH30S0NgG9J2L1vF1mC_rLQ9t194p1lCan7ZhaAc3Z4UpUt0i_SeVjrVXImOAxNP2eYT97lr3MT4kEzID7wBrFXO-UknrAjzOmVff4wkLQzI4ZNx9Bbtrl7l7tZGuPnLgWxZDMBFqxD8oCah2QVUn9PmULv953P8MSnyh8SBg
Host: localhost:8080

5.4.2. Retrieve Domain Configuration By Domain ID Query Parameters

Parameter Description

domainId

Domain ID

5.4.3. Sample Retrieve Domain Configuration By Domain ID Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 743

{
  "id" : "5f09551dea78f80ca7c29aee",
  "domainId" : "1",
  "authorizationCodeType" : "alphanumeric",
  "authorizationCodeTypeProperties" : { },
  "authorizationCodeTTLSeconds" : 600,
  "maxAuthorizationTTLSeconds" : 86400,
  "refreshTokenEnabled" : true,
  "accessTokenProvider" : "jwt",
  "accessTokenProperties" : { },
  "refreshTokenProvider" : "alphanumeric",
  "refreshTokenProperties" : { },
  "issuerId" : "mmadu.com",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551dea78f80ca7c29aee"
    },
    "domainIdentityConfiguration" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551dea78f80ca7c29aee"
    }
  }
}

5.4.4. Retrieve Domain Configuration By Domain ID Response Fields

Path Type Description

id

string

Domain Identity Configuration ID

domainId

String

The Domain Id

authorizationCodeType

String

The format of authorization code generated in authorization_code grant type flow

authorizationCodeTypeProperties

Object

Properties for customizing the authorization code generation

authorizationCodeTTLSeconds

Number

Validity of the authorization code in seconds

maxAuthorizationTTLSeconds

Number

Maximum validity of Granted Authorization in seconds (regardless of any authorization type)

refreshTokenEnabled

Boolean

If enabled, refresh token will be issued if the flow supports it.

accessTokenProvider

String

The provider used for generating access tokens

accessTokenProperties

Object

Properties for customizing the access token generation

refreshTokenProvider

String

The provider used for generating refresh tokens

refreshTokenProperties

Object

Properties for customizing the refresh token generation

issuerId

String

issuer id of the domain

5.5. Retrieving all Domain Configurations

A GET /admin/repo/domainIdentityConfigurations request will retrieve all domain configurations.

Authority identity_config.read

5.5.1. Sample Retrieve All Domains

GET /admin/repo/domainIdentityConfigurations HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmlkZW50aXR5X2NvbmZpZy5yZWFkIiwiZXhwIjoxNTk0NDQ3MTM3LCJpYXQiOjE1OTQ0NDcxMzIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.fsoOIpIik4HcXdPkRFWZOl7JP2ULG-P2Dcm4syrRsSJJnoyEodiEzzUmbrKtzFDuYImJPVM1CFwVEGZJcpE6Ox6WP4tVbCcYyO7eF8sryZz7HyCIzOrZ628g4jf_YlDZn0KNHcnOETwi5b9WvTgauOg3Fq3C5v_WFW7Z0QmKSV66sP9Ww3gXGAqqA1757Tk21OevBA7T_JotohSuf3LDy2Tt8hhlZ1YhioiJpQZQYKFo9OE09aFYZfTPZj0sEp2Cj3I75JJTiglzbJw-FpRjTG1JpcnoJmJxZVDjOZ3ZH3WlEEzA7YwSKU63PurNz9ft9D_ZoytRNXIu9WUu9NeCnA
Host: localhost:8080

5.5.2. Sample Retrieve All Domains Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 3135

{
  "_embedded" : {
    "domainIdentityConfigurations" : [ {
      "id" : "5f095508ea78f80ca7c29ac1",
      "domainId" : "0",
      "authorizationCodeType" : "alphanumeric",
      "authorizationCodeTypeProperties" : { },
      "authorizationCodeTTLSeconds" : 600,
      "maxAuthorizationTTLSeconds" : 3600,
      "refreshTokenEnabled" : true,
      "accessTokenProvider" : "jwt",
      "accessTokenProperties" : {
        "credentialId" : "5f095508ea78f80ca7c29ac0"
      },
      "refreshTokenProvider" : "alphanumeric",
      "refreshTokenProperties" : { },
      "issuerId" : "mmadu.com",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f095508ea78f80ca7c29ac1"
        },
        "domainIdentityConfiguration" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f095508ea78f80ca7c29ac1"
        }
      }
    }, {
      "id" : "5f095508ea78f80ca7c29ac9",
      "domainId" : "1212",
      "authorizationCodeType" : "alphanumeric",
      "authorizationCodeTypeProperties" : { },
      "authorizationCodeTTLSeconds" : 600,
      "maxAuthorizationTTLSeconds" : 3600,
      "refreshTokenEnabled" : true,
      "accessTokenProvider" : "jwt",
      "accessTokenProperties" : {
        "credentialId" : "5f095508ea78f80ca7c29ac8"
      },
      "refreshTokenProvider" : "alphanumeric",
      "refreshTokenProperties" : { },
      "issuerId" : "mmadu.com",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f095508ea78f80ca7c29ac9"
        },
        "domainIdentityConfiguration" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f095508ea78f80ca7c29ac9"
        }
      }
    }, {
      "id" : "5f09551cea78f80ca7c29ae9",
      "domainId" : "1",
      "authorizationCodeType" : "alphanumeric",
      "authorizationCodeTypeProperties" : { },
      "authorizationCodeTTLSeconds" : 600,
      "maxAuthorizationTTLSeconds" : 86400,
      "refreshTokenEnabled" : true,
      "accessTokenProvider" : "jwt",
      "accessTokenProperties" : { },
      "refreshTokenProvider" : "alphanumeric",
      "refreshTokenProperties" : { },
      "issuerId" : "mmadu.com",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29ae9"
        },
        "domainIdentityConfiguration" : {
          "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29ae9"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations"
    },
    "profile" : {
      "href" : "http://localhost:8080/admin/repo/profile/domainIdentityConfigurations"
    },
    "search" : {
      "href" : "http://localhost:8080/admin/repo/domainIdentityConfigurations/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}

5.5.3. Retrieve All Domains Response Fields

Path Type Description

_embedded.domainIdentityConfigurations.[].id

string

Domain Identity Configuration ID

_embedded.domainIdentityConfigurations.[].domainId

String

The Domain Id

_embedded.domainIdentityConfigurations.[].authorizationCodeType

String

The format of authorization code generated in authorization_code grant type flow

_embedded.domainIdentityConfigurations.[].authorizationCodeTypeProperties

Object

Properties for customizing the authorization code generation

_embedded.domainIdentityConfigurations.[].authorizationCodeTTLSeconds

Number

Validity of the authorization code in seconds

_embedded.domainIdentityConfigurations.[].maxAuthorizationTTLSeconds

Number

Maximum validity of Granted Authorization in seconds (regardless of any authorization type)

_embedded.domainIdentityConfigurations.[].refreshTokenEnabled

Boolean

If enabled, refresh token will be issued if the flow supports it.

_embedded.domainIdentityConfigurations.[].accessTokenProvider

String

The provider used for generating access tokens

_embedded.domainIdentityConfigurations.[].accessTokenProperties

Object

Properties for customizing the access token generation

_embedded.domainIdentityConfigurations.[].refreshTokenProvider

String

The provider used for generating refresh tokens

_embedded.domainIdentityConfigurations.[].refreshTokenProperties

Object

Properties for customizing the refresh token generation

_embedded.domainIdentityConfigurations.[].issuerId

String

issuer id of the domain

5.6. Updating a Domain Configuration

A PATCH request can be used to partially update a domain configuration.

Authority identity_config.update

5.6.1. Sample Retrieve All Domains

PATCH /admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aec HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5pZGVudGl0eV9jb25maWcudXBkYXRlIiwiZXhwIjoxNTk0NDQ3MTM3LCJpYXQiOjE1OTQ0NDcxMzIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.NnFlKZEn40eVDbimF4hypkTA6ICchdgN8lv_lhIy3B1EUmfhS4p8aL1YB5lTSdN3ZrNrtL-osdUFvf7fT5Z7InAoChotnfvFD089bwlnODs880miA4RJ73CuxjeRbPla_uRm3RDTVhsmh7juzoHJuZEbCCs-WZk9BgDdcTSvGQgeMigTgr4VeG-Q1j2hfSiEwFUo0HMqkKyXatb_gs63SW0AJUCqtL05O0uaxDOV0V0mjGVCwIVhBT0576yQLcxEssIpAO2s8rFVqClCasF75UnJEe05wvbCNVhU7R33XldLadx2Vir_ZceMHiR2vV9AcCpzFQsGa0Tvep84ioT9WQ
Content-Length: 35
Host: localhost:8080

{"authorizationCodeTTLSeconds":300}

5.6.2. Sample Retrieve All Domains Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

5.7. Removing a Domain Configuration

A DELETE request can be used to remove a domain configuration.

Authority identity_config.delete

5.7.1. Sample Domain Configuration Delete Request

DELETE /admin/repo/domainIdentityConfigurations/5f09551cea78f80ca7c29aea HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMzIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5pZGVudGl0eV9jb25maWcuZGVsZXRlIiwiZXhwIjoxNTk0NDQ3MTM3LCJpYXQiOjE1OTQ0NDcxMzIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.YarNp8O52oqPpNioUEJ5km53dHhoPWNjqm0Jf2b0wB7PWg6-lBitm4IgDf_xJiuXZht92pMcF7IRr19W1ESx7uAMv2F8Bo6PFBn4YBxe-67pTYZO6cgOBu1jJoESCSNZrdY7p5_TN8P3azlRT9a5gcfQltVQ2TnzFi00TkQsnsYcZS0ImiZiG7Z5qxL_vtz-e_8XIQ2Kk6-Btvmj0sTXNk9UlF53ifRiVZrYeGWhHChVeUnH19FVRdpjgDymsyAxWgUGkRxnuBtpiVVQmwDwpDwdxg168bCFeYBDD607JgibJ-LqVeKNODZoNOUmluaFwJwja6spzxr6Sz9garFj2w
Host: localhost:8080

5.7.2. Domain Configuration Delete Path Variables

Table 2. /admin/repo/domainIdentityConfigurations/{domainIdentityConfigurationId}
Parameter Description

domainIdentityConfigurationId

The domain identity configuration id

5.7.3. Sample Delete Domain Configuration Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

6. Managing Clients

Clients hold information about an application. A Client object is a convenient way to group Client Instances.

6.1. Creating a Client

A POST request will create a client.

Authority: client.create

6.1.1. Sample Client Creation Request

POST /admin/repo/clients HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnQuY3JlYXRlIiwiZXhwIjoxNTk0NDQ3MTU3LCJpYXQiOjE1OTQ0NDcxNTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.LpRreKM1gUxE8wQKHunNoMPATphHK07QcmNguemKGIUePYzBnp4kI4JKedMePkSKvHRZjTQd3sPcE2rGcbWgkqOCfozjcomz9ok6lQjO4017YSfz8XiblfOIZv9uK4KAarytjRBaz7Fz8xTt0J8MXTCe5dPanUk0cJbuW4Obb962a2-4uBb8HKdsvBua_FO3EkAqyITqgWp7xuajnaiDrB0KYV5fkmU8KxpRWfGUi-vKoGuYhL1GChB5o4Z_CiBIdkBtVO6OgSVVU4vGGnKmcZmjTYQCgSjW2pTjTf8cNHRDpyLg0nrAZUJhN_8vwEDaFMCH91yn_ZgHiJ1OE6vYmQ
Content-Length: 239
Host: localhost:8080

{
  "name" : "Email Client",
  "category" : "third_party",
  "logoUrl" : "http://an.email.com/favicon",
  "applicationUrl" : "http://an.email.com",
  "code" : "A12345",
  "domainId" : "1",
  "tags" : [ "email", "communications" ]
}

6.1.2. Client Creation Request Fields

Path Type Description

id

string

Client ID

name

String

The client’s name

category

String

The client’s category

tags

Array

List of tags to further categorize clients

logoUrl

String

The Client’s logo

applicationUrl

String

The client’s main application home page url

code

String

The client code

domainId

String

the ID of the domain

6.1.3. Sample Client Creation Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0f
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

6.2. Retrieving a Client

A GET request will retrieve a client by id.

Authority: client.read

6.2.1. Sample Client Retrieval Request

GET /admin/repo/clients/5f095530ea78f80ca7c29b0d HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmNsaWVudC5yZWFkIiwiZXhwIjoxNTk0NDQ3MTU3LCJpYXQiOjE1OTQ0NDcxNTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.S-_wQjpD06f-SsZXRy4MApNAq-gV96rPbwv6-3hj_6jIL_mZiODClBEnWtMNa7FhSWC8hlFlTsIZ8SY7lCRlUUMDBFpgRETEZfv3GWYN7IWeF3_VhNy2uGM4RG04X9I6Q5AESOW1Zs0mdl1npJK5mjezpgEEAb5f1wQdwdSwelCRgm2pTvLkfroERYJkFqyVlaqpu4iPZ0seKtI9dWa-hOrdabpsas03y8cTwlK18tP7aIOvT3lly6GspAUN1QcqywJ1Zs-vzo2bYGePcqMb7bNoQ9fY6pQkj6CgP1Zimad7R-6splV9bNJeChfMuyifXaAKohaGnnwkaFY-GXUrTg
Host: localhost:8080

6.2.2. Client Retrieval Request Path

Table 3. /admin/repo/clients/{clientId}
Parameter Description

clientId

The client ID

6.2.3. Sample Client Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 516

{
  "id" : "5f095530ea78f80ca7c29b0d",
  "domainId" : "1",
  "name" : "Email Client",
  "code" : "A12345",
  "applicationUrl" : "http://an.email.com",
  "logoUrl" : "http://an.email.com/favicon",
  "category" : "third_party",
  "tags" : [ "email", "communications" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0d"
    },
    "client" : {
      "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0d"
    }
  }
}

6.3. Retrieving Clients By Domain ID

A GET request will retrieve clients by domain id.

Authority: client.read

6.3.1. Sample Client Retrieval by Domain Request

GET /admin/repo/clients/search/findByDomainId?domainId=1 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnQucmVhZCIsImV4cCI6MTU5NDQ0NzE1NywiaWF0IjoxNTk0NDQ3MTUyLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.kLK1G_8lAEl8OqvqD7dcxnO0MTVjNJ-d30P69ya1jxmvi8tutgNjb1vgsMuznZRcURwtomb38HfNIgWAOVcmbKbsR3zN1v98Cmnv6LQBqY2xZmm3WYjA_ECiGX7oBrdLxvtgsxh3QCgWZ-9MUI7PyvYETkTPWEymvzlogYrQzdwRWDDNW3qRt2DbaBWsAplz_j8DVwLwJiLQmpysyFVQL_9hvgjB7g9nAC6h4vnXHW8bi8Wga0UU1fta8GzwuA7wcsmbX3-wsSm-iAmfNxjxr-X_5Uw0C6oE7Q39X9KKSQ60X8Pd56EmZDgB4jSZhG5QD-3E3-jIKGL8gT5IknH2hA
Host: localhost:8080

6.3.2. Client Retrieval By Domain Query Parameters

Parameter Description

domainId

Domain ID of the client

6.3.3. Sample Client Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 2056

{
  "_embedded" : {
    "clients" : [ {
      "id" : "5f095530ea78f80ca7c29b0c",
      "domainId" : "1",
      "name" : "New Email Client",
      "code" : "A12345",
      "applicationUrl" : "http://an.email.com",
      "logoUrl" : "http://an.email.com/favicon",
      "category" : "third_party",
      "tags" : [ "email", "communications" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0c"
        },
        "client" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0c"
        }
      }
    }, {
      "id" : "5f095530ea78f80ca7c29b0d",
      "domainId" : "1",
      "name" : "Email Client",
      "code" : "A12345",
      "applicationUrl" : "http://an.email.com",
      "logoUrl" : "http://an.email.com/favicon",
      "category" : "third_party",
      "tags" : [ "email", "communications" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0d"
        },
        "client" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0d"
        }
      }
    }, {
      "id" : "5f095530ea78f80ca7c29b0e",
      "domainId" : "1",
      "name" : "Email Client",
      "code" : "A12345",
      "applicationUrl" : "http://an.email.com",
      "logoUrl" : "http://an.email.com/favicon",
      "category" : "third_party",
      "tags" : [ "email", "communications" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0e"
        },
        "client" : {
          "href" : "http://localhost:8080/admin/repo/clients/5f095530ea78f80ca7c29b0e"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/clients/search/findByDomainId?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}

6.4. Updating a Client

A PATCH request will update a client.

Authority: client.update

6.4.1. Sample Client Update Request

PATCH /admin/repo/clients/5f095530ea78f80ca7c29b0c HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnQudXBkYXRlIiwiZXhwIjoxNTk0NDQ3MTU3LCJpYXQiOjE1OTQ0NDcxNTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.Wlsp-5RywZ2OXB6j85pqripIg2wIP5VZjlR-0io9NKaw9_u_Zfi5pxw7b53bRx6zwaUMNfwaaTvC8TvGAtIjCDwUiMhzFh8QZLFulPhRDmTXwVfx2tfsrcQLalQXPxfzS8RyVlcvyQPgFxLfr9RURtlTKZt_H2mb1qSohJc7FdHx51pFAXt7bM4ZguV0k5ydewDo1cvYoIRRIxqLpgg6fojympMYaa2ccQ_ly2Pf1sboXWQEiIJmtgcvvlJXdwH9-ieU97e5kOxDExhXWo42m5eMuenWOvJy47Vgd7DgcO4bq8Tr1fZFuWeNVRvSh75BT20El11OZkjCSoh-zy1jtQ
Content-Length: 27
Host: localhost:8080

{"name":"New Email Client"}

6.4.2. Sample Client Update Path

Table 4. /admin/repo/clients/{clientId}
Parameter Description

clientId

The client ID

6.4.3. Sample Client Update Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

6.5. Removing a Client

A DELETE request will delete a client.

Authority: client.delete

6.5.1. Sample Client Removal Request

DELETE /admin/repo/clients/5f095530ea78f80ca7c29b0b HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnQuZGVsZXRlIiwiZXhwIjoxNTk0NDQ3MTU3LCJpYXQiOjE1OTQ0NDcxNTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.jUOnWuz-G9zCZAWaZ3Ja827vz0UKc0nbna2ZSHcZdU5FWvhYOKKB2expUYiT-15rDYn6ELUV1Jl5dQxpJPcHQ2s8_nJsQ-yYvHC7Fid1KrGYr7c1XXZFBjtac4KYZv_r663JAHK6cLKT_f43TD6laLm7dpjH37-lG12TsvjiRA96DPV1jF-wqcf-ycOMkHf85WDYahlC-lHJSDSc-RrQRE9UqRkzC-h1TpoU7aDRpOBWuuL4n5Y0lmsLqjN75LYRhQCklv5_Y3airD0Z1f3kmnIJJmrMpy5Vu_2_i2EBVBC7O3qtvjIr72SpUVoeZ7ZQWdIeR-1-rgFdaCqj2wD2Bg
Host: localhost:8080

6.5.2. Sample Client Removal Path

Table 5. /admin/repo/clients/{clientId}
Parameter Description

clientId

The client ID

6.5.3. Sample Client Removal Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7. Managing Client Instances

A Client Instance represents an oauth client. An application can have several client instances for its different components if needed.

7.1. Creating a Client Instance

A POST request will create a client instance.

Authority: client_instance.create

7.1.1. Sample Client Instance Creation Request

POST /admin/repo/clientInstances HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnRfaW5zdGFuY2UuY3JlYXRlIiwiZXhwIjoxNTk0NDQ3MTE4LCJpYXQiOjE1OTQ0NDcxMTMsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.G342OICMp0TOVQKPAvH2M4Hi0zkx9rMZOu2b7Wx8rnaDbTO95lp_-au1tVTX2D0HVM3CaUU-ikIgc3mYWFt0Tkhf4vyHsRhEaSHuJkot6TS--7LXZYE_r4LgbScfJSkcnccPHLvsgXOld8gRGejIIOzEj6WSUsjpxsmSa45G76F15_HSh4FQ0VACXe6e8nTSW9kLSVJOT0m5hj_-XS6kNEyJiRz9HrIrcXp88wFl7iMdidkF79L1aWSDG-lrE3YJi1JTyWngBeb3QYvqNFkfT11xBkx_Y4DnF9IHNkymZw383K0-gORAELVM2AQ84WZ09jRRwrLi28HVupXel_hTRA
Content-Length: 626
Host: localhost:8080

{
  "clientId" : "5f095509ea78f80ca7c29ad7",
  "clientType" : "CONFIDENTIAL",
  "clientProfile" : "web_app",
  "tlsEnabled" : true,
  "includeUserRoles" : true,
  "includeUserAuthorities" : true,
  "tokenCategory" : "bearer",
  "domainId" : "1",
  "resources" : [ "test" ],
  "authorities" : [ "admin" ],
  "redirectionUris" : [ "https://myapp.com/callback", "https://localhost:8080/callback" ],
  "allowedHosts" : [ "localhost", "teamapt.com", "32.32.182.34" ],
  "supportedGrantTypes" : [ "authentication_code", "client_credentials" ],
  "credentials" : {
    "type" : "secret",
    "secret" : "1234"
  }
}

7.1.2. Client Instance Creation Request Fields

Path Type Description

id

string

Client ID

clientId

String

The client ID

clientType

String

Either CONFIDENTIAL or PUBLIC

clientProfile

String

Client profile category: either web_app, user_agent_app, or native_app, custom profiles may be used.

credentials

Varies

Client credentials

identifier

String

The client’s generated identifier used for authorization and authentication

allowedHosts

Array

The host names to be used with this client

redirectionUris

Array

The redirection urls permitted to be used with this client

supportedGrantTypes

Array

The grant types these clients are permitted to use

tlsEnabled

Boolean

Whether TLS should be made compulsory

domainId

String

the ID of the domain

resources

Array

The resource ids of the resources the client should have access to

authorities

Array

The list of authorities granted to the client

includeUserRoles

Boolean

Include user’s roles in the token info

includeUserAuthorities

Boolean

Include user’s authorities in the token info

tokenCategory

String

The type of tokens expected e.g. 'bearer'

credentials.type

String

The client’s credential type (for now, secret)

credentials.secret

string

The client secret (if credential type is secret)

7.1.3. Sample Client Instance Creation Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/admin/repo/clientInstances/5f095509ea78f80ca7c29ad9
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7.2. Retrieving a Client Instance

A GET request will retrieve a client instance by id.

Authority: client_instance.read

7.2.1. Sample Client Instance Retrieval Request

GET /admin/repo/clientInstances/5f095508ea78f80ca7c29ad6 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmNsaWVudF9pbnN0YW5jZS5yZWFkIiwiZXhwIjoxNTk0NDQ3MTE3LCJpYXQiOjE1OTQ0NDcxMTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.oIFjB6RoO1HGLHKlA6CNOrz8VzF5Afcx_IJt_Upb5q39uOiwP55JTcgQ3CTbYouZUybFpiwgW1GdGGEmKpi_MJuiAJ4fhJkf8ASkh8kJl_aXfz5dY-XODGKY__VY_EMiXlZ5Onhl0MEz7ZL5Bz8SXBHo1ZZt4yeSASwNwSAULc3y4vs1DqJT-PvSdG53QDTomMeDv5kFW-z79T9wHKKFKRzW8VmUjTU3GRiUbd4n1rbnXU_QSZegbDah2WjivkzUUyDKeJTVWGbl0e0_Hcos78zk5qdqOZh_niWvNNE7PMQ1f9Lw9hfuRODewPrpMHZHElXrRIjsXrQARO8rBZ0Uuw
Host: localhost:8080

7.2.2. Client Instance Retrieval Request Path

Table 6. /admin/repo/clientInstances/{clientInstanceId}
Parameter Description

clientInstanceId

The client instance ID

7.2.3. Sample Client Instance Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1313

{
  "id" : "5f095508ea78f80ca7c29ad6",
  "clientId" : "5f095508ea78f80ca7c29ad4",
  "clientType" : "CONFIDENTIAL",
  "clientProfile" : "web_app",
  "credentials" : {
    "type" : "secret"
  },
  "identifier" : "1111",
  "redirectionUris" : [ "https://redirect.com/callback", "https://localhost:832/callback" ],
  "allowedHosts" : [ "192.168.99.100" ],
  "tlsEnabled" : true,
  "supportedGrantTypes" : [ "authorization_code", "client_credentials" ],
  "domainId" : "1",
  "resources" : [ "test" ],
  "authorities" : [ "admin" ],
  "issueRefreshTokens" : true,
  "authorizationCodeGrantTypeTTLSeconds" : 86400,
  "implicitGrantTypeTTLSeconds" : 3600,
  "passwordGrantTypeTTLSeconds" : 86400,
  "accessTokenTTLSeconds" : 300,
  "refreshTokenTTLSeconds" : 3600,
  "clientCredentialsGrantTypeTTLSeconds" : 86400,
  "includeUserRoles" : false,
  "includeUserAuthorities" : false,
  "includeUserGroups" : false,
  "scopes" : [ ],
  "tokenCategory" : "bearer",
  "authorizationProfile" : {
    "autoApproveScopes" : false
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/clientInstances/5f095508ea78f80ca7c29ad6"
    },
    "clientInstance" : {
      "href" : "http://localhost:8080/admin/repo/clientInstances/5f095508ea78f80ca7c29ad6"
    }
  }
}

7.3. Retrieving Clients Instances By Domain ID

A GET request will retrieve client instances by domain id.

Authority: client_instane.read

7.3.1. Sample Client Instance Retrieval by Domain Request

GET /admin/repo/clientInstances/search/findByDomainId?domainId=1 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnRfaW5zdGFuY2UucmVhZCIsImV4cCI6MTU5NDQ0NzExOCwiaWF0IjoxNTk0NDQ3MTEzLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.A9LoJRTa_nI_EG2vVL0StkMNYwTHV_UBxyqLIN4C-9pLeQdXT_83HJJJyCzllK3sH2Q-qgHFuUP6qzUox4iEC_t9Bf8I3qxNmnyUjrbZTiVC7v7hMxY1Sjk8wHvOzZMVJvCL_CEKYFtpX63GtffHGKTGGnBh666_HwLPIthGD5QjVBuIpRpM0Wt598klSJuTJGZhkzGlDLOif-Sh5WT3mALwhqqtE8jnU9arUp623RuvHrX6g9leHUntM2jvN22Or3RNQ03iAHruvoof0-fhfNjKGPsddLrjlHxtdpyZ4Rz2qjwE3bKGQTwMstNFvWIllmLOCON778DYwQxNao4mpw
Host: localhost:8080

7.3.2. Client Instances Retrieval By Domain Query Parameters

Parameter Description

domainId

Domain ID of the client instance

7.3.3. Sample Client Instance Retrieval by Domain Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1781

{
  "_embedded" : {
    "clientInstances" : [ {
      "id" : "5f095509ea78f80ca7c29adc",
      "clientId" : "5f095509ea78f80ca7c29ada",
      "clientType" : "CONFIDENTIAL",
      "clientProfile" : "web_app",
      "credentials" : {
        "type" : "secret"
      },
      "identifier" : "1111",
      "redirectionUris" : [ "https://redirect.com/callback", "https://localhost:832/callback" ],
      "allowedHosts" : [ "192.168.99.100" ],
      "tlsEnabled" : true,
      "supportedGrantTypes" : [ "authorization_code", "client_credentials" ],
      "domainId" : "1",
      "resources" : [ "test" ],
      "authorities" : [ "admin" ],
      "issueRefreshTokens" : true,
      "authorizationCodeGrantTypeTTLSeconds" : 86400,
      "implicitGrantTypeTTLSeconds" : 3600,
      "passwordGrantTypeTTLSeconds" : 86400,
      "accessTokenTTLSeconds" : 300,
      "refreshTokenTTLSeconds" : 3600,
      "clientCredentialsGrantTypeTTLSeconds" : 86400,
      "includeUserRoles" : false,
      "includeUserAuthorities" : false,
      "includeUserGroups" : false,
      "scopes" : [ ],
      "tokenCategory" : "bearer",
      "authorizationProfile" : {
        "autoApproveScopes" : false
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/clientInstances/5f095509ea78f80ca7c29adc"
        },
        "clientInstance" : {
          "href" : "http://localhost:8080/admin/repo/clientInstances/5f095509ea78f80ca7c29adc"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/clientInstances/search/findByDomainId?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

7.4. Retrieving Clients Instances By Domain ID and Client ID

A GET request will retrieve client instances by domain id and client id.

Authority: client_instane.read

7.4.1. Sample Client Instance Retrieval by Domain and Client Request

GET /admin/repo/clientInstances/search/findByDomainIdAndClientId?domainId=1&clientId=5f095508ea78f80ca7c29ace HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnRfaW5zdGFuY2UucmVhZCIsImV4cCI6MTU5NDQ0NzExNywiaWF0IjoxNTk0NDQ3MTEyLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.Z6mkPGTHiE4SsRMCirJyZxUZUTw8cDYY_gRL4OVWP28zKKDtfHUmp1AJiiB73tCYeZtXakEFtyt883tLct_HQvxMoMS0XyBuedzba1nEB-Gssbd8yXLbA4-KQAiZeZFe3a430eN9rOqdT6H99IQxjEdjdr5FDd1iNHXUQMS4zLp55QIK4DQM8tcudFfu9fx1dhyOxDnJ13P7woOOXCFjwCJUM1e0srGXFYQ20tbpGOBXfAiqBPjLLrj7n3TN1R0Cupp25825zPYmkbmw5fs7tUkgSxpeoqCuoF2Ng2LknnaTuAhCHvIEcAka0IkqBbw3WMnBDsdOLgw4xtHC9T3B3Q
Host: localhost:8080

7.4.2. Client Instances Retrieval By Domain and Client Query Parameters

Parameter Description

domainId

Domain ID of the client instance

clientId

The client’s ID

7.4.3. Sample Client Instance Retrieval by Domain and Client Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1792

{
  "_embedded" : {
    "clientInstances" : [ {
      "id" : "5f095508ea78f80ca7c29ad0",
      "clientId" : "5f095508ea78f80ca7c29ace",
      "clientType" : "CONFIDENTIAL",
      "clientProfile" : "web_app",
      "credentials" : {
        "type" : "secret"
      },
      "identifier" : "1111",
      "redirectionUris" : [ "https://redirect.com/callback", "https://localhost:832/callback" ],
      "allowedHosts" : [ "192.168.99.100" ],
      "tlsEnabled" : true,
      "supportedGrantTypes" : [ "authorization_code", "client_credentials" ],
      "domainId" : "1",
      "resources" : [ "test" ],
      "authorities" : [ "admin" ],
      "issueRefreshTokens" : true,
      "authorizationCodeGrantTypeTTLSeconds" : 86400,
      "implicitGrantTypeTTLSeconds" : 3600,
      "passwordGrantTypeTTLSeconds" : 86400,
      "accessTokenTTLSeconds" : 300,
      "refreshTokenTTLSeconds" : 3600,
      "clientCredentialsGrantTypeTTLSeconds" : 86400,
      "includeUserRoles" : false,
      "includeUserAuthorities" : false,
      "includeUserGroups" : false,
      "scopes" : [ ],
      "tokenCategory" : "bearer",
      "authorizationProfile" : {
        "autoApproveScopes" : false
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/clientInstances/5f095508ea78f80ca7c29ad0"
        },
        "clientInstance" : {
          "href" : "http://localhost:8080/admin/repo/clientInstances/5f095508ea78f80ca7c29ad0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/clientInstances/search/findByDomainIdAndClientId?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

7.5. Updating a Client Instance

A PATCH request will update a client instance.

Authority: client_instance.update

7.5.1. Sample Client Instance Update Request

PATCH /admin/repo/clientInstances/5f095509ea78f80ca7c29adf HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnRfaW5zdGFuY2UudXBkYXRlIiwiZXhwIjoxNTk0NDQ3MTE4LCJpYXQiOjE1OTQ0NDcxMTMsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.aUIeCdeg5F3qWsRWy2FAByaiv717ecSnhlKMkrP1Yafp0_v-KiRjZef8kVbNBBJH6RL9i9ZizX1fMty8X6iLgE3Ej7NJro462c891rWUk0h6qJWIoOrD-Np_AxrJUN-kqBi4KC-gvVAFAy-mxaO83YdU4aIuPwnsRq8nI7p09isqcCHE5K8Ez-z_aAIiaE5Ywj4XBkT5EpkWWELdtDAG0jMMG4iQVHykHJkttr7ngWgY-Qn8q3dvVmCwM03uZmzePe0_4NAiVR4dK7Hsc17lwmvx3xxuJ_KE4Fhy-67Z9ILTU8yCKzs26LP9dBszic08bPOpvMkeLt-qHk2sRJjMtw
Content-Length: 20
Host: localhost:8080

{"tlsEnabled":false}

7.5.2. Sample Client Instance Update Path

Table 7. /admin/repo/clientInstances/{clientInstanceId}
Parameter Description

clientInstanceId

The client instance ID

7.5.3. Sample Client Instance Update Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7.6. Removing a Client Instance

A DELETE request will delete a client instance.

Authority: client_instance.delete

7.6.1. Sample Client Instance Removal Request

DELETE /admin/repo/clientInstances/5f095508ea78f80ca7c29ad3 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jbGllbnRfaW5zdGFuY2UuZGVsZXRlIiwiZXhwIjoxNTk0NDQ3MTE3LCJpYXQiOjE1OTQ0NDcxMTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.HTcR20Bkl76sWrTBGB0X8ylNEfetrdpxnJUVXVIOxIxdHRb8-VuJJq7Ee0zCtgYmPbp7vLBNBzdhJHypwxaXI9rOF2Wowv0VGeEnheNqKZVU_5UOJqMxo4iYrD6h2ulR4d4pk-pJ_uIeTHn5Sia6A2FG_Fdz8WygOaTsaaE4jDveZgHpgF9CRbo7dnMiwGaQtqZ88gzIe19frkxnyiamoQtTuql3mhaS_QIWPlDmFsJr1iwclgPvVX59qRbXd8cYXpCczAnCgvgoBgI9XHQ_yF8h_uie9bFrbigJIqxc9sNTRdxOrR10-vVVlD9KCgDpNflIk0olMirnMuF75GMNaA
Host: localhost:8080

7.6.2. Sample Client Instance Removal Path

Table 8. /admin/repo/clientInstances/{clientInstanceId}
Parameter Description

clientInstanceId

The client instance ID

7.6.3. Sample Client Instance Removal Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8. Managing Scopes

Scopes are sets of authorities that the user can grant to a client. In Mmadu, a scope contains an array of authorities (can be roles or authorities) that the client wants to obtain from the user. The user sees the list of scopes at the authorization page and can select which scopes to approve and which to reject.

Linking scopes to authorities provide a convenient way of grouping authorities in a manner that is presentable to the user.

Assuming a client is requesting for four authorities from the user create_book, edit_book, create_class and edit_class. To present this to the user, an admin can create two scopes: manage_book and manage_class. The manage_book will be linked to the create_book and edit_book authorities while the manage_class will be linked to the create_class and edit_class authority.

At the authorizaton page, the user will see that he needs to select from two scopes manage_class and manage_book instead of looking through four authorities. Any scope that the user approves, the authorities are automatically approved. The scope code and authority identifiers will be added to the scope field in the authorization.

8.1. Creating a Scope

A POST request will create a scope.

Authority: scope.create

8.1.1. Sample Scope Creation Request

POST /admin/repo/scopes HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMDYsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5zY29wZS5jcmVhdGUiLCJleHAiOjE1OTQ0NDcxMTEsImlhdCI6MTU5NDQ0NzEwNiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.lgZMPHV0Y-yEtzQHUfGfkK6NWQSQlpE1ue-Br8CTg_AeyWvh0K5OYqdmaaXrda_9bfl5wIpa00jehRHA_HOQ2rDfnLsoKqXmSixrxPLEEVGf_nnRFzSMP_nevfiXEi4kH3xoeDpywkSjYu8CwrawxjcjktrX05-62quFAYqDjUdvbHycRs6l3PIOzpSZDKhTuQzhuKTlAaE5DGK9c5LgPccX1yz6HgQ0TIdcda-faQm3i2_3BP7XGcVwEKoccyia6B34LM7Iv9n9Y65pPsF3A6XquWgPGNnUrwD43k19evpgvPVoiWv1pQNF6npGJ62zw3CNUQxx3rbtGDWK05TH8A
Content-Length: 150
Host: localhost:8080

{
  "name" : "Email Scope",
  "code" : "test.mail",
  "description" : "Email Contacts",
  "domainId" : "1",
  "authorities" : [ "view_users" ]
}

8.1.2. Scope Creation Request Fields

Path Type Description

id

string

Scope ID

name

String

The scope’s name

code

String

The scopes identification code

authorities

Array

List of authorities and roles associated with this scope

description

String

The scopes description

domainId

String

The domain id of the scope

8.1.3. Sample Scope Creation Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29aba
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.2. Retrieving a Scope

A GET request will retrieve a client by id.

Authority: scope.read

8.2.1. Sample Scope Retrieval Request

GET /admin/repo/scopes/5f095502ea78f80ca7c29abe HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMDYsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLnNjb3BlLnJlYWQiLCJleHAiOjE1OTQ0NDcxMTEsImlhdCI6MTU5NDQ0NzEwNiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.hDuqytJWxIaD4FNJ0ZBBhaQbsive_kd-6KD0Bbbnee2ycLpf6qRgndhZwmt39wbGmt7r53nuu79cvQAMqOBj0xq-1AVJF0d1421dMI13uhV2Yc5leoCTqs9fuALQsLkJQJWM1oGz3IhSDF9ntu-JRKAMyPJ60kknZ5WRvIqsQNFllRpm8AZiTlqjQWdFp1ku7z8_0be2_lZH4CAhBZTYZ4p9CeFGqB5Qt-VLYKF_-1berH0lg3HoMHy9xgCu9I2rqtD3eDzha49pXi-WT3oL0TSohM8b35r3ajjTD31Y6v_RQ_1IX7HOkv5A9RnK0zuLNTmfJkrMk-C-3s6e3Gyfbw
Host: localhost:8080

8.2.2. Scope Retrieval Request Path

Table 9. /admin/repo/scopes/{scopeId}
Parameter Description

scopeId

The scope ID

8.2.3. Sample Scope Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 424

{
  "id" : "5f095502ea78f80ca7c29abe",
  "domainId" : "1",
  "code" : "test.mail",
  "name" : "Email Scope",
  "description" : "Email Contacts",
  "authorities" : [ "view_users" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abe"
    },
    "scope" : {
      "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abe"
    }
  }
}

8.3. Retrieving all Scopes in Domain

A GET request will retrieve all scopes in a domain

Authority: scope.read

8.3.1. Sample All Domain Scopes Retrieval Request

GET /admin/repo/scopes/search/findByDomainId?domainId=1 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMDYsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5zY29wZS5yZWFkIiwiZXhwIjoxNTk0NDQ3MTExLCJpYXQiOjE1OTQ0NDcxMDYsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.XInDzg_DJvkzCWJLmWdwFJAXtTNBVf0EZoSJQppxKoOTY0Tewud3-vfxM8170YYMJ2o4W_ek_OclfWNBawUsuDoNMgMy-9k7ZYRagzI9zyShrDWi1etQTsIzPX6Z5z6dfUO99fDOKQj3azJDWg4VuhEFx9M-Dnqg76R6NRjSkmI9Z0so08jrhqkP9CUltfFBUZgQl75Ls8z5a-TaJIA8x8b5ra8TXEXNyvFif_v05LMoPW0hnwyagfyK42PIKysr83K2CIwCI7P5AYMNz8TtV054hrjUw3ww0ANgkCYoPo-aMx4-BishQ0Gvz1Bjxa_5quOcamO9UR26oXlPTMZqCA
Host: localhost:8080

8.3.2. Scope All Domain Scopes Retrieval Query Parameter

Parameter Description

domainId

Domain ID of the scope

8.3.3. Sample All Domain Scopes Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1628

{
  "_embedded" : {
    "scopes" : [ {
      "id" : "5f095502ea78f80ca7c29aba",
      "domainId" : "1",
      "code" : "test.mail",
      "name" : "Email Scope",
      "description" : "Email Contacts",
      "authorities" : [ "view_users" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29aba"
        },
        "scope" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29aba"
        }
      }
    }, {
      "id" : "5f095502ea78f80ca7c29abc",
      "domainId" : "1",
      "code" : "test.mail",
      "name" : "New Email",
      "description" : "Email Contacts",
      "authorities" : [ "view_users" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abc"
        },
        "scope" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abc"
        }
      }
    }, {
      "id" : "5f095502ea78f80ca7c29abd",
      "domainId" : "1",
      "code" : "test.mail",
      "name" : "Email Scope",
      "description" : "Email Contacts",
      "authorities" : [ "view_users" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abd"
        },
        "scope" : {
          "href" : "http://localhost:8080/admin/repo/scopes/5f095502ea78f80ca7c29abd"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/scopes/search/findByDomainId"
    }
  }
}

8.4. Updating a Scope

A PATCH request will update a scope.

Authority: scope.update

8.4.1. Sample Scope Update Request

PATCH /admin/repo/scopes/5f095502ea78f80ca7c29abc HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMDYsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5zY29wZS51cGRhdGUiLCJleHAiOjE1OTQ0NDcxMTEsImlhdCI6MTU5NDQ0NzEwNiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.U1mx7pIht34BuyV9v0pq1aw0kUGTg-k6NgspVCM3AUIo99fdp7kvtm40zP5bYEYOebltOzwhmkN98l1U6CmcPb01W6i5icHloT_RcVRkzp7PWujlxRTncdU0qrW3rI-bGZq3HcHY3eP1JFao_v8Z6P3F9ZEdiubFvg6PX1klmQgLKqZPWpFthuUZyYcxqmR7oBdz-cXUip60IIu6c27q-PLzI7UAgRT_RtAirCwo1xIZoMtjYXRkUvZmCOSqvAkzXUV-5t_q7JtTniTH75KyGFikl_FFUseao_Fs5KTjntTj4yOyy6PUiZU56dy39fqvmjlf58SenbSnNIqHu7cbnQ
Content-Length: 20
Host: localhost:8080

{"name":"New Email"}

8.4.2. Sample Scope Update Path

Table 10. /admin/repo/scopes/{scopeId}
Parameter Description

scopeId

The scope ID

8.4.3. Sample Scope Update Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.5. Removing a Scope

A DELETE request will delete a scope.

Authority: scope.delete

8.5.1. Sample Scope Removal Request

DELETE /admin/repo/scopes/5f095502ea78f80ca7c29abb HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxMDYsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5zY29wZS5kZWxldGUiLCJleHAiOjE1OTQ0NDcxMTEsImlhdCI6MTU5NDQ0NzEwNiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.Vmk1613DZV7Xt68KnvNoEeTCOqbx2MHcY5OqCbICJyc8Rr5I1KxKY4PZiI_LjdZyJtaNE4lHuSBP4XPqByJSR7mCH-mcc58J3LvvbUopHot8ZhlhbVhyDKqfNVPcPOqyCrTT5eBrBlyGoWNipyyFpMmheMBpcJDN4tDg_QxE6SQb_udO5Cr3Kau_no8JU2jNJ-5vPM7-qFnhc6WM0X_M4gyqxFriPwFZsLlPbxqUSfdtPGfxnPaHxIgDKIrxHNMJU5i3hNNCCFMeV5pqM9YjMiCIyFhzwtz_9CESOWH73osgcjNWzSjvJXcXBCkLT2DN3KvKY6RVBSzxXeE0CxyzOQ
Host: localhost:8080

8.5.2. Sample Scope Removal Path

Table 11. /admin/repo/scopes/{scopeId}
Parameter Description

scopeId

The scope ID

8.5.3. Sample Scope Removal Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9. Managing Resources

Resources represent individual API’s or services that clients can access. Every client instance specifies a list of resource identifiers that it is supposed to utilize. These resources must be created and maintained using these apis. On authorization, the list of resource identifiers that the client has access to will be included in the aud claim of the tokens. This claim can be enforced by resource servers by checking that its resource identifier is contained in the aud claim before processing the request.

9.1. Creating a Resource

A POST request will create a resource.

Authority: resource.create

9.1.1. Sample Resource Creation Request

POST /admin/repo/resources HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5yZXNvdXJjZS5jcmVhdGUiLCJleHAiOjE1OTQ0NDcxNTcsImlhdCI6MTU5NDQ0NzE1MiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.TFFDGTKk7rBOpr9ayoml9fT2JGRxzBO7Ej-Spaq1yb2L1hlxK2nvrnJ1iLJDHzi6Tp5H8lO1XjiTOXa0RS1JXaNEXyehnFZYN_mg-KX4n-qRO4RpXprN3PXsfUpcwk9CbWJ7zeua9VvX27nSQDvt2jKzMjaBEDv4pWLYj6pwwkgFaLWM1EJ6hzQkLfOmczkXQcS5341EVowsLIhx2-elF1piwB4QtcztznfJ9PP6bs_iSl4UQ7vK-ZAm8gMnXhfBF3J-86iYnbiU6dFgnDTqVhCx6R5o68ieiqQLqNPXzLqYtjUmmjYaV7BzVubMsGcXgI2NzDVBmXQVC73h6URk9g
Content-Length: 121
Host: localhost:8080

{
  "name" : "email",
  "identifier" : "email-service",
  "description" : "Email Microservice",
  "domainId" : "1"
}

9.1.2. Resource Creation Request Fields

Path Type Description

id

string

Resource ID

name

String

The resource’s name

identifier

String

The resource’s identifier

description

String

A description of the resource

domainId

String

The domain ID

9.1.3. Sample Resource Creation Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: http://localhost:8080/admin/repo/resources/5f095530ea78f80ca7c29b0a
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9.2. Retrieving a Resource

A GET request will retrieve a client by id.

Authority: resource.read

9.2.1. Sample Resource Retrieval Request

GET /admin/repo/resources/5f095530ea78f80ca7c29b09 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLnJlc291cmNlLnJlYWQiLCJleHAiOjE1OTQ0NDcxNTcsImlhdCI6MTU5NDQ0NzE1MiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.lUa_7MdYLficcZQsmeh3Wj1WNxNABSAK8fupokZ1OX34yifpMd8u1DOx2Xiq0IZrElSLnptprzuL1KMdUmJIsJ65hxCmGmONZCaqnylThdp3qnjAAYRQo7bwi9rhDNiKc5MfWHLRFZ8z6p9HFAt3vm3zTGwyA4yTJqgNNTPdwF3rsa71n6XzXDLlnN6FlzkdKFdo2IzNnPaIzFu-t0rMlURwxIPDEOAoDxCWr2cCQnN7ivOzC8Jj2LLxLLjPIpz6O8xazqZ8BwmB-J_mQJiXCB9YBvfR0355Y7fWpqetgvv0UBkH0BodLiDqIg578BgvRc8GXjejlvd1SLhPCOGO5w
Host: localhost:8080

9.2.2. Resource Retrieval Request Path

Table 12. /admin/repo/resources/{resourceId}
Parameter Description

resourceId

The resource ID

9.2.3. Sample Resource Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 450

{
  "id" : "5f095530ea78f80ca7c29b09",
  "domainId" : "1",
  "identifier" : "email-service",
  "name" : "email",
  "description" : "Email Microservice",
  "supportedTokenCategories" : [ "bearer" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/resources/5f095530ea78f80ca7c29b09"
    },
    "resource" : {
      "href" : "http://localhost:8080/admin/repo/resources/5f095530ea78f80ca7c29b09"
    }
  }
}

9.3. Retrieving all Resources in Domain

A GET request will retrieve all resources in a domain

Authority: resource.read

9.3.1. Sample All Domain Resources Retrieval Request

GET /admin/repo/resources/search/findByDomainId?domainId=1 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5yZXNvdXJjZS5yZWFkIiwiZXhwIjoxNTk0NDQ3MTU2LCJpYXQiOjE1OTQ0NDcxNTEsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.TezYKNL8mf-QRp9RE9WMys0wZ7FcfAAC8ZTXtmfOae4YGYdkJOfj6XyV7tYr1ZbiuxLFbSi4McPsxNuAawfDacirjU4CKuRA-uHSjpSw2uGSOs4IyTa2JgNRCNwPzHtsqG0h-8_RhsWReAWAFDa7GS4lGLgURjjhjmpUhVbYfZtldtU2H7wFjs7HF1_5G_ymVgvPJygnV4DoKk_y0hQH7iWAd5zffrGvmtacFCewE6JUD4aGp3VPjprKhZuZY6nBOPczzy3Jw-Dq5PnfWo9JrIZIGsAv1ZEBlTGuhKhcYqel23YGsIdE1mPEkKKroSoA-xqM46XcHRhcujlN-zTJwg
Host: localhost:8080

9.3.2. Resource All Domain Resources Retrieval Query Parameter

Parameter Description

domainId

Domain ID of the resource

9.3.3. Sample All Domain Resources Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1335

{
  "_embedded" : {
    "resources" : [ {
      "id" : "5f09552fea78f80ca7c29b07",
      "domainId" : "1",
      "identifier" : "email-service",
      "name" : "New Email Resource",
      "description" : "Email Microservice",
      "supportedTokenCategories" : [ "bearer" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/resources/5f09552fea78f80ca7c29b07"
        },
        "resource" : {
          "href" : "http://localhost:8080/admin/repo/resources/5f09552fea78f80ca7c29b07"
        }
      }
    }, {
      "id" : "5f09552fea78f80ca7c29b08",
      "domainId" : "1",
      "identifier" : "email-service",
      "name" : "email",
      "description" : "Email Microservice",
      "supportedTokenCategories" : [ "bearer" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/admin/repo/resources/5f09552fea78f80ca7c29b08"
        },
        "resource" : {
          "href" : "http://localhost:8080/admin/repo/resources/5f09552fea78f80ca7c29b08"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/admin/repo/resources/search/findByDomainId?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

9.4. Updating a Resource

A PATCH request will update a resource.

Authority: resource.update

9.4.1. Sample Resource Update Request

PATCH /admin/repo/resources/5f09552fea78f80ca7c29b07 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5yZXNvdXJjZS51cGRhdGUiLCJleHAiOjE1OTQ0NDcxNTYsImlhdCI6MTU5NDQ0NzE1MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.C7hACpL3O7UOVTDh1aVaAOlRZC7n5oCceBLhE05XxSLTIUvSU_2o75HhABnwTsqAs4n97MhYF3AULyXUiTNQTK6c2LNkoy_QWIG9KhftUvqT7PFCOqI2oqkkxARiSWwe5_aFgpTmD5MycNXyJt1pxaTALSEEjNoG-FV7WyhLjDwW3mnsO2DquH8WhR7OM9ZWNhnK1a-pRAZYRriB2KtGPQkYAD6VRmDsn0pLixeXU4SkbSJVGG_e368CU4weeaQG_3c9dZa-EuASYAwq61N-sGeHgtGTim5KUBlUzUC_HuKCQEDLvCDP0Sq8kMo2aZEdZLni33c-G62CmRiZdoXsTw
Content-Length: 29
Host: localhost:8080

{"name":"New Email Resource"}

9.4.2. Sample Resource Update Path

Table 13. /admin/repo/resources/{resourceId}
Parameter Description

resourceId

The resource ID

9.4.3. Sample Resource Update Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9.5. Removing a Resource

A DELETE request will delete a resource.

Authority: resource.delete

9.5.1. Sample Resource Removal Request

DELETE /admin/repo/resources/5f09552fea78f80ca7c29b06 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcxNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5yZXNvdXJjZS5kZWxldGUiLCJleHAiOjE1OTQ0NDcxNTYsImlhdCI6MTU5NDQ0NzE1MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.GV6KU9VCoRslhYQuz6EM-mzLdYjO-9aQaEK2MG2A6wuC4RCj7pE1lgL1hqG-QZOuqCBvkkrgGrVVFufZ93Tc1PasCQMM0kzXJibqKQsK9BLpOxHBvVOmZb2ouC5LY80mu10FIfynVvRNedlUXRh-nZLYMoS_ZOUmzVS5JSrIpjXCgDewhU4p5hyRphy2s72mMpaOs8NxMvwhkGIh-IEjXaqfwfZpg8sEha3T8JX8cZx6bXSX8f7nr8curXYQgwpuo7ufoaojWZhFj0txcpVpnpXmEuRPlJG6EYwFp_ud188a9JeZBCYSx-ms0JlY3KWq69xiSNScfJWZFKqip_-2kQ
Host: localhost:8080

9.5.2. Sample Resource Removal Path

Table 14. /admin/repo/resources/{resourceId}
Parameter Description

resourceId

The resource ID

9.5.3. Sample Resource Removal Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

10. Managing Credentials

Credentials are secrets that are used for encryption, hashing or signature creation and verification. Credentials are used in different aspects of Mmadu Identity, so it is important to know how to manage them.

10.1. Generating a Credential

To Generate a credential, we make a POST request with the type and properties of the credential we want to generate.

POST /admin/domains/1/credentials HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTI1NDg1MTksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jcmVkZW50aWFsLmNyZWF0ZSIsImV4cCI6MTU5MjU0ODUyNCwiaWF0IjoxNTkyNTQ4NTE5LCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.C8n13eYVq9QHkzF4JOPgTSNMY1-rDS0BdU6XMR_AuypofkqXsHZRQGxTsS0pZWBEh3OCbjU8ZzXZLjievxCNRCLpcUj3JAECh5wFI4Y2xKQum5scwPRjT-5tKgxgpJiMsXD_3AJxfj74KwJ3b9WALh0JzfXGqkfMmW8PAN7Wn9NwZY0qscGhqxUho540t33eURYCNHJrql0N_9Z0zK2Iki2bfcjJa2vGUuTITMzDyOJn1mBC_FkNQNd5xHKUV7X1SVbiRYZSeDRfseSHEdonw0T3HOvPQN7KK3MQjvaC4ZmNvRp6awXdofz7jS1OKSkdrY9AWL5584HGzXziWkF2Ug
Accept: text/plain
Content-Length: 22
Host: localhost:8080

{
  "type" : "rsa"
}
Only RSA Keys are supported at this time.

10.2. Obtaining a Credential Verification Key

A credential verification key is a key used for verifying signatures created by its counter part private key.

A GET request will obtain a credential verification key by credential id. A hex encoded string is returned.

GET /admin/domains/1/credentials/5f0954fbea78f80ca7c29aaf/verificationKey HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6WyJ0ZXN0Iiwic2FtcGxlIl0sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDcwOTksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMS5jcmVkZW50aWFsLnJlYWQiLCJleHAiOjE1OTQ0NDcxMDQsImlhdCI6MTU5NDQ0NzA5OSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.NGb0BOc_PH2c6NC0NfaPBQtbqKtrfvyri8bFejYHYR9jZizwuEGnvvR7ZolhBnvf7jTq43RrM-ct0m5u4wAd7LrM-lGqIBw40cmMMEItnVD0v8HGozBbxo6F6PqqrU3p9Ix9wbf5EICqle0dmZmzDGKPzUdRNttpwTn3r-QHgrSInPUvfNpI7qzDqYRsDO7mz4wUow90OJhGr2yhFVlNAO2R6nLFmb-v29Eu33WWGNDGbKTh6MaaMLdDI591f5yrDEiTAK5pZ9MzaKmyiRU8euhIvcvkLpMa1eYJ0CNkYCOPotgDugiHb1t7CxF6KLoLsEzL9v0KCOQ4n1yAhANbiQ
Host: localhost:8080
Table 15. /admin/domains/{domainId}/credentials/{credentialId}/verificationKey
Parameter Description

domainId

domain for the credentials to be crated in

credentialId

the credential id

11. Oauth 2.0 Authorization Flows for Mmadu Identity

Here, we will itemize the steps to utilize the various grants.For each of these flows, you must have a client identifier, client_id and a client secret client_secret.

11.1. Authorization Code Grant Flow

  • Redirect to user the authorize endpoint: http://:/oauth/authorize?client_id=&response_type=code&redirect_uri= The redirect_uri parameter may be omitted if you have configured one and only one redirect_uri on the ClientInstance.

  • The user will first sign in if a session does not exist.After this, an authorization page will be displayed.

  • The user selects the scopes to be approved, and checks the "I want to authorize this application" and clicks "Submit".

  • The user is redirected to a the callback uri specified in the redirect_uri parameter or in the configuration of the ClientInstance. Here, a code query parameter is passed to the client as shown:

http://localhost:8080/oauth/callback?code=sdAd2adsfWaC

  • The client implements the callback to extract the authorization code in the code query param and use it to request for an access token.This is as shown below:

Confidential Client Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Authorization: Basic bXkuYXBwLmFkbWluOjEyMzQ1Njc4OTA=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=K5s0BKyfF4
CONFIDENTIAL clients are required to provide an authentication when accessing the token api.PUBLIC clients are not required to do so.If no authentication is provided, you need to add the client_id parameter as shown below:
Public Client Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=K5s0BKyfF4&client_id=sample.client
If a redirect_uri was specified, then a redirect_uri parameter is required.

  1. If authorization is successful, an access_token and a refresh token is returned.

{
    "access_token": "eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWVmODVkMzQ2ODdiZDI2MmU3Njk4Y2IyIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTMzMzUzMjEsInVzZXJfaWQiOiIxMTExIiwic2NvcGUiOiJhLiouKiogc3VwZXJfYWRtaW4gci5zdXBlcl9hZG1pbiIsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5MzMzNTYyMSwiaWF0IjoxNTkzMzM1MzIxLCJqdGkiOiIxNWMzMjJlZC02MWI1LTQzNWEtOWVmMy02YzBjOThhMDQ4OTYiLCJjbGllbnRfaWQiOiJtbWFkdV9hZG1pbiJ9.hdgo4JnswWI63N-vI-BDEgukBaVsHttqRw3s_JCLmbjISzU3z9fOq4y8y_mZa4sZc3tVHf9xETVefBfjLZl2pIGMRLdjYZac0_iPcOYzmXjP9eOcnYCjhjMTb02ZYhYpWRQt83gWUt1U4apoxQstXW0sKbdaqCa_oaDbg0drW-ComCg0cssgXsePMHqlvQUjn6GC7IdYgNh-FBSpNOiQ1XLOS4O62EgA75nO6OOwt4bTRdNLM9mBFRb8av89W4fzAKnL0l4_KXZM6hmFamvfCLS4FRBegBy463zvRSSHodhx75Q6r5kn_MgXToMWOt-urOjXiCehB2E7boynw9tbmw",
    "token_type": "bearer",
    "expires_in": 1593335621,
    "refresh_token": "oxz46a4uaq11oC47FWQy",
    "jti": "15c322ed-61b5-435a-9ef3-6c0c98a04896"
}

11.1.1. Auto Approving Scopes

The client instance can be configured to skip authorization i.e grant all of the clients scopes without displaying the authorization page. This functionality is desired to create a seemless login for the user. To configure the client instance to auto approve scopes, we set the authorizationProfile.autoApproveScopes property to true;

Client Innstance Configuration for Auto Approve scopes
{
"authorizationProfile": {
  "autoApproveScopes": true
}
}

11.2. Refresh Token

The refresh token grant type is used for requesting new access_tokens.If a refresh_token is included in the access_token response then you can use the refresh token to obtain a new access_token once the old one expires.This endpoint generates a new access_token and refresh_token.This also supports Public and Confidential Clients.

Confidential Client Refresh Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Authorization: Basic bXkuYXBwLmFkbWluOjEyMzQ1Njc4OTA=
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=oxz46a4uaq11oC47FWQy
Public Client Refresh Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=oxz46a4uaq11oC47FWQy&client_id=sample.client

11.3. Client Credentials Grant Flow

In client credentials, the client requests a token on behalf of itself.

  • Make a request to the token endpoint as shown:

Confidential Client Credentials Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Accept: application/json
Authorization: Basic bW1hZHVfYWRtaW46MTIzNDU2Nzg5MA==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
Public Client Credentials Token Request
POST /clients/token HTTP/1.1
Host: localhost:15553
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=sample.client

A token response will be returned if authentication is successful.

{
    "access_token": "eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWVmODJiOWQxZmI2OTI3NDg3ODI3NmYwIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTMzMjIzOTcsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5MzMyNTk5NywiaWF0IjoxNTkzMzIyMzk3LCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiYTVkYzJjMzktZjc4Zi00ZWU4LWE4OGQtNTU5NGEzNGUyNzU0IiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.TpsXmmqc8DKA-5lx12W6JK5QXpbzpjkqPEBgU5oj__I9151v9bXX16xGF2A_gGoHK7JunGZ7OjuPFaPyS7rahuq-9KNAjQ_ZbBncytkVtNUf-h0WS-E3zM-5qnMTf5THU0zeTgii04U-rMgOgr3Qy6LKnYZraA1iUakX-MmR1Vkubf807im3_YqfjP3w86Xv62ipUuWiL64d-PZiYnM20s3lp5wHAWsFTFJPVHMPk0K96CHppDzYHh6WZF_kF9c5lPxqZFBmu8QY3Xfz8somAEq4jbldB7GW2W72gs7MTXtkO0omdedf3cwFItfQFWCHhLg8EyWhXUZu4SFqV5uThA",
    "token_type": "bearer",
    "expires_in": 1593325997,
    "jti": "a5dc2c39-f78f-4ee8-a88d-5594a34e2754"
}
Refresh tokens are not enabled for client_credentials grant type.

11.4. Implicit Flow

In implicit flow, the token details are returned in the redirect uri. The second step of obtaining a token is removed. This grant type requires no authorization.

The state parameter is required and should be set by the client. This value is opaque and is returned when calling the redirect uri.

  • The client is redirected to the authorization page as shown below:

Implicit Authorization Endpoint example
http://localhost:15553/oauth/authorize?client_id=mmadu_admin&response_type=token&state=di298383sdfad

After the user authorizes the request, the user is redirected back to the client redirect uri with token parameters as shown below:

Implicit Authorization Endpoint Redirection Url Example
http://localhost:18005/oauth/callback?access_token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWVmZGUzNWYyOWU0OTM0MmY2ODhkZjQ4IiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTM2OTcxMTksInVzZXJfaWQiOiIxMTExIiwic2NvcGUiOiJzdXBlcl9hZG1pbiIsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5MzY5NzQxOSwiaWF0IjoxNTkzNjk3MTE5LCJqdGkiOiJlYWU3ZjYwNS0zNzc1LTQ4NzAtOWVkNC1mNzAyNzEwNWEzOWUiLCJjbGllbnRfaWQiOiJtbWFkdV9hZG1pbiJ9.l3UXI10Wwh6JTstziv_IXaVBDV0HGUKzDAK8nbnLEd2uprWcF40h8y34QCIrvuKRW0y9XzMf5d77kMJeCsGyCG_HWEquEBZdecawlpR3R9cuSZNsK96qO3grltms2xHP0FwMXvu2hAZEdJHIBSqf5ECwjYM_8kqVzxU8h5yQyBFUwVKgS0clqcHg7nn_hT8JETicptBLVgxR6vCH8H9a5qIS5LNu_7vxrwp5nMlE7oXbbcgb6NHqYvdhEy9aby6gwJ-zbpMBidHT65rQGS8AakS03d21GfJmUTwPw9yszXyF6JrrI5aTL-4FCV72WknIprZKryjVRwy2TsAvUia6AQ&scope=super_admin&state=di298383sdfad&token_type=bearer&expires_in=1593697419

The client should implement the call back to extract the token details and clear the sensitive details from the url.

11.5. Resource Owner Credentials Flow

This flow involves making a token request with the credentials of the resource owner. This is useful in creating custom login screens that reside on third party applications. Because credentials are collected in third party applications there is a risk of exposing user credentials.

The flow is as follows:

  • The client displays a form for the user to input credentials.

  • The client collects this input and makes a token request to authenticate user and obtain tokens.

Confidential Client Resource Owner Token Request
POST /clients/token HTTP/1.1
Host: localhost:10084
Accept: application/json
Authorization: Basic bW1hZHVfYWRtaW46MTIzNDU2Nzg5MA==
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=password&scope=super_admin+visitor
Public Client Resource Owner Token Request
POST /clients/token HTTP/1.1
Host: localhost:10084
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=password&scope=super_admin+visitor&client_id=my.client

  • If Authorization succeds a token response is returned. A refresh_token is added to the response if the domain supports it.

{
    "access_token": "eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWVmZTA1YjUyMGVhMWEzZWZlODFjMDEyIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTM3MDU5MDksInVzZXJfaWQiOiIxMTExIiwic2NvcGUiOiIiLCJpc3MiOiJtbWFkdS5jb20iLCJleHAiOjE1OTM3MDYyMDksImlhdCI6MTU5MzcwNTkwOSwianRpIjoiNjliN2JjMDUtMGQ1OC00ZjQyLTg4YzUtYzg0ZDYwMzhiMWViIiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.xndAPkdwanAgwDE1LC2RuzaVLjbwwwgcBAnrUg49VLheOXBKcNPzPno4OlYXnSjl1zG9tIo-DocdNiFpsV34Fv41jIm_TcmzY8lmHEs1eznrolk1wcvze5Hjg9omD1smQMNgUUhTONOnJRDy-MXK3cmfgacQHb8Tlx94GfYxv611YsArLhHBhY_RN4-ClRtdsHP06Qndt8n5Mteo0QFxDc_UcdUfCXQ13WRG0JBIILq8yuqnVJ7jRrzxsvQpPyN0lpE79a4lvONJhxshy3Nwy4iCIkL9ONSmNiwHgrIaRWc-1gfRSGJYYf7z2DpS7PzEZlFeQhVSipPCA86WZWx0wg",
    "token_type": "bearer",
    "expires_in": 1593706209,
    "refresh_token": "Os3v8kb4RZYMEBxERly4",
    "jti": "69b7bc05-0d58-4f42-88c5-c84d6038b1eb"
}

  • If a refresh_token is returned, the client can request for a new access token once the old one expires using the refresh token grant.

12. Token Verification

Once access tokens are issued to a client, the client uses the access token to access a resource. A resource needs to be able to:

  1. Verify that the token comes from the correct source

  2. Verify that the token has sufficient claims to access the resource.

12.1. JWT Token Signature Verification

Mmmadu Identity provides two approaches to obtaining verification keys.

12.1.1. From Credentials

  1. Retrieve the domain configuration by domain id

  2. Get the credentialId property of the accessTokenProperties and use this to obtain the verification key using the credential verification key retrieval api

12.1.2. From Authorization Server Metadata

Mmadu Identity exposes a JWK uri for clients to dynamically obtain the verification key. A GET request will obtain the jwk set needed to verify the access tokens.

GET /metadata/my-domain-id/jwks.json HTTP/1.1
Host: localhost:15553

This returns a standard JWK set JSON response that can be used to create the verification key.

{
    "keys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "kid": "123",
            "n": "3bXAtU2gab_UTpVIOXA-bnJ8eJwhuClodIQyYiy3-mZIMJ3Bzh5nh017lDzma0HySzSZEfNcwiCeYXZ8EVcMNskT794FjCdMgXA_wcfr_A58d1trSr43_u5z3C5HaBF_AIU5vMLiLgi7-HpAoXB1gjFuPY6Rlr0O46dqZVoNpKq3Xo9KMe_FK6sTYneimDdcgDgyv60_CmysKGx4HGae0floU1Kad7YfCUw_K6yAJS-d4UvDte0IVYqdAC-kee-07nwFVq3OSO3L6wtVz_KSST4-wafNiBwhkqdhPS2VBhacUZWH7LAKDEeYvH14J7Knk2ZoAkMO_Ng9fMnwux-26w"
        }
    ]
}

12.2. Claim Verification

Cliams are associated with each token generated. The resource server can read these claims and use it to authenticate a client request. The following are the supported claims:

Table 16. Token Claims
Claim Description Supported Grant Types

domain_id

The domain id of the user and the client

All

sub

The Authorization ID

All

aud

Audience, the list of resource identifiers that this token is meant for

All

iss

The issuer of this token

All

exp

The expiry date of this token

All

iat

The time at which the token was issued

All

nbf

The time at which the token becomes active

All

authorities

The authorities of the client instance (configured when creating the client instance)

Client Credentials

jti

The token identifier

All

client_id

The client identifier

All

user_id

The user id of the user that granted the authority

Authorization Code, Implicit, Password

username

The username of the user that granted the authority

Authorization Code, Implicit, Password

scopes

A space delimited list of roles, scopes and authorities granted to the client by the user

Authorization Code, Implicit

13. Token Introspection

To get metadata about a token, make a POST /clients/checkToken.

Token Introspection Request With Confidential Client and Basic Authentication
POST /clients/checkToken HTTP/1.1
Host: localhost:15553
Accept: application/json
Authorization: Basic bW1hZHVfYWRtaW46MTIzNDU2Nzg5MA==
Content-Type: application/x-www-form-urlencoded

token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNmRkNTQzYTM2NWE2Nzg4N2VhNGU4IiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyODUzOTUsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI4ODk5NSwiaWF0IjoxNTk0Mjg1Mzk1LCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiNTQzYzQ0MGQtNTQwNy00YTQwLWFlMzEtMjM2NzA3MzcwZjM3IiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.jIjprf3KlL_5CBvB4EJAoJIHxL2sUQzxY5aDaAsXDFnXYwC7FMS8jXAWPEDrcnLjgX0IorzZxc98H2zS87x06rT1pZ54_MqofdR_QjPyxheKMnhc0JrFgW9bgDGDSRBw1ufBJityFcyi4jQXPj_9IGYUvJkqPxoVwm9zVfvMQvTLBioyEtgXZH0x86Kxny98mMkgaYbsDDwrIrJCzM8ey32JymZ4M00Ao1-gTM6PbqgZhtBMkp4i7QSHOmKX7NzsQZaPYVp1hVrYuTzHpxUu5j1LZBCsas8II_46XU64GWKl1pRvjLkKd2r9kKvgo8tH5gD9FrbNde0OVmEp_qyhCw
Token Introspection Endpoint with Confidential Client (Authentication body)
POST /clients/checkToken HTTP/1.1
Host: localhost:10084
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=mmadu_admin&client_secret=1234567890&token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNmRkNTQzYTM2NWE2Nzg4N2VhNGU4IiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyODUzOTUsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI4ODk5NSwiaWF0IjoxNTk0Mjg1Mzk1LCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiNTQzYzQ0MGQtNTQwNy00YTQwLWFlMzEtMjM2NzA3MzcwZjM3IiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.jIjprf3KlL_5CBvB4EJAoJIHxL2sUQzxY5aDaAsXDFnXYwC7FMS8jXAWPEDrcnLjgX0IorzZxc98H2zS87x06rT1pZ54_MqofdR_QjPyxheKMnhc0JrFgW9bgDGDSRBw1ufBJityFcyi4jQXPj_9IGYUvJkqPxoVwm9zVfvMQvTLBioyEtgXZH0x86Kxny98mMkgaYbsDDwrIrJCzM8ey32JymZ4M00Ao1-gTM6PbqgZhtBMkp4i7QSHOmKX7NzsQZaPYVp1hVrYuTzHpxUu5j1LZBCsas8II_46XU64GWKl1pRvjLkKd2r9kKvgo8tH5gD9FrbNde0OVmEp_qyhCw
Token Introspection Endpoint with Public Client
POST /clients/checkToken HTTP/1.1
Host: localhost:15553
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=mmadu_admin&token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNmRkNTQzYTM2NWE2Nzg4N2VhNGU4IiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyODUzOTUsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI4ODk5NSwiaWF0IjoxNTk0Mjg1Mzk1LCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiNTQzYzQ0MGQtNTQwNy00YTQwLWFlMzEtMjM2NzA3MzcwZjM3IiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.jIjprf3KlL_5CBvB4EJAoJIHxL2sUQzxY5aDaAsXDFnXYwC7FMS8jXAWPEDrcnLjgX0IorzZxc98H2zS87x06rT1pZ54_MqofdR_QjPyxheKMnhc0JrFgW9bgDGDSRBw1ufBJityFcyi4jQXPj_9IGYUvJkqPxoVwm9zVfvMQvTLBioyEtgXZH0x86Kxny98mMkgaYbsDDwrIrJCzM8ey32JymZ4M00Ao1-gTM6PbqgZhtBMkp4i7QSHOmKX7NzsQZaPYVp1hVrYuTzHpxUu5j1LZBCsas8II_46XU64GWKl1pRvjLkKd2r9kKvgo8tH5gD9FrbNde0OVmEp_qyhCw

This returns a json response with the token claims listed in [_claim_verification]

Example:

{
    "active": true,
    "client_id": "mmadu_admin",
    "token_type": "bearer",
    "exp": 1594288995,
    "iat": 1594285395,
    "nbf": 1594285395,
    "sub": "5f06dd543a365a67887ea4e8",
    "aud": [
        "my.service.1",
        "my.service.2"
    ],
    "iss": "mmadu.com",
    "jti": "543c440d-5407-4a40-ae31-236707370f37",
    "authorities": [
        "view",
        "edit"
    ]
}

14. Revoking Tokens

Tokens can be revoked using the revoke token endpoint, POST /clients/revokeToken.

Token Revocation for Confidential Clients (Basic Authentication)
POST /clients/revokeToken HTTP/1.1
Host: localhost:10084
Accept: application/json
Authorization: Basic bW1hZHVfYWRtaW46MTIzNDU2Nzg5MA==
Content-Type: application/x-www-form-urlencoded

token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNzAyM2E2NjMyOTA1OWU1ZTcxNmMxIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyOTQ4NDIsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI5ODQ0MiwiaWF0IjoxNTk0Mjk0ODQyLCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiMDBjMzZkMzItOTcwNy00NzU5LTkzMTQtMGM3NDhkOTljZWRkIiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.fom22MxbPtJ2P_N6ukWotr229IgTBGSuEh088IbngfreChFHwoZNf9kmoVWdWhAUXjDyn0aQlKEla76u-kxVwal3AbDfZoOYb0oT36BL6wNQIsQ9qj3ZVZ3dLlAntvt5EMi-cpTCKsCi8eWvUYW4kNkZQ_y5NJzup_I4Io1S3eh4VFR_4Or_2nwJTCsXVtmW8MI8R17q1mIqlzcRfkFChurdDkL77zMn_d7yTKRquJf8QmBd1tZxc580ZTsTNX1bIOQgn8G4PKwPQVQ_tFX58RYDM1YOidkgJ4SdV-2AaL4wk7eU0qNx0tywBYpjgoM7x4jOJ8a69YkfpfmCNL8a7w
Token Revocation for Confidential Clients (Authentication body)
POST /clients/revokeToken HTTP/1.1
Host: localhost:10084
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=mmadu_admin&client_secret=1234567890&token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNzAyM2E2NjMyOTA1OWU1ZTcxNmMxIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyOTQ4NDIsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI5ODQ0MiwiaWF0IjoxNTk0Mjk0ODQyLCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiMDBjMzZkMzItOTcwNy00NzU5LTkzMTQtMGM3NDhkOTljZWRkIiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.fom22MxbPtJ2P_N6ukWotr229IgTBGSuEh088IbngfreChFHwoZNf9kmoVWdWhAUXjDyn0aQlKEla76u-kxVwal3AbDfZoOYb0oT36BL6wNQIsQ9qj3ZVZ3dLlAntvt5EMi-cpTCKsCi8eWvUYW4kNkZQ_y5NJzup_I4Io1S3eh4VFR_4Or_2nwJTCsXVtmW8MI8R17q1mIqlzcRfkFChurdDkL77zMn_d7yTKRquJf8QmBd1tZxc580ZTsTNX1bIOQgn8G4PKwPQVQ_tFX58RYDM1YOidkgJ4SdV-2AaL4wk7eU0qNx0tywBYpjgoM7x4jOJ8a69YkfpfmCNL8a7w
Token Revocation for Public Clients
POST /clients/revokeToken HTTP/1.1
Host: localhost:10084
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=mmadu_admin&token=eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJkb21haW5faWQiOiIwIiwic3ViIjoiNWYwNzAyM2E2NjMyOTA1OWU1ZTcxNmMxIiwiYXVkIjpbInVtcyIsImlkcyIsInVmcyJdLCJuYmYiOjE1OTQyOTQ4NDIsImlzcyI6Im1tYWR1LmNvbSIsImV4cCI6MTU5NDI5ODQ0MiwiaWF0IjoxNTk0Mjk0ODQyLCJhdXRob3JpdGllcyI6WyJhLiouKioiLCJyLiouKioiXSwianRpIjoiMDBjMzZkMzItOTcwNy00NzU5LTkzMTQtMGM3NDhkOTljZWRkIiwiY2xpZW50X2lkIjoibW1hZHVfYWRtaW4ifQ.fom22MxbPtJ2P_N6ukWotr229IgTBGSuEh088IbngfreChFHwoZNf9kmoVWdWhAUXjDyn0aQlKEla76u-kxVwal3AbDfZoOYb0oT36BL6wNQIsQ9qj3ZVZ3dLlAntvt5EMi-cpTCKsCi8eWvUYW4kNkZQ_y5NJzup_I4Io1S3eh4VFR_4Or_2nwJTCsXVtmW8MI8R17q1mIqlzcRfkFChurdDkL77zMn_d7yTKRquJf8QmBd1tZxc580ZTsTNX1bIOQgn8G4PKwPQVQ_tFX58RYDM1YOidkgJ4SdV-2AaL4wk7eU0qNx0tywBYpjgoM7x4jOJ8a69YkfpfmCNL8a7w