Configuring Authorization Servers

The Authorization Server (AS) is the first FPX domain specific object with reference to Wallet configuration. The Authorization Server has a central role in defining most other domain objects (Resource Types, Scopes, Data Sources, and clients service providers)

• Use of this API depends on: Configuring Organizations -> id

Request Attributes

The API call shown below to create an Authorization Server entry also includes the creation of other entities that the Authorization Server depends on: OAuth Provider and OAuth Client. The attributes in the request are described in the following tables according to the entity to which they belong.

OAuth Client

Parameter	Description	Example value	Required	Localizable
clientId	An identifier for the OAuth Client (the Authorization Server in this case) to use with the Wallet. This value is required for the client_id parameter when configuring the Wallet UI.	authserver-client-id	Yes	No
clientSecret	An secret for the OAuth Client (the Authorization Server in this case) to use with the Wallet	authserver-client-secret	Yes	No
baseUrl	The base URL of the OAuth Client	{{AUTH_SERVER_URI}}	Yes	No
redirectUris	An array which defines a list of the URIs that the Wallet will permit redirects to on behalf of this client	{{AUTH_SERVER_URI}}/transaction/callback	No	No

OAuth Provider

Parameter	Description	Example value	Required	Localizable
name	A human-readable name for the OAuth Provider	Identos Auth Server	Yes	Yes
clientId	This value is used to identify the Wallet Server with the OAuth Provider (the Authorization Server in this case)	wallet-identos-clientid	Yes	No
clientSecret	A secret the Wallet Server uses with the OAuth Provider (the Authorization Server in this case)	wallet-identos-clientsecret	Yes	No
issuerUri	The base URL of the OAuth Provider	{{AUTH_SERVER_URI}}	Yes	No
clientAuthenticationMethod	The authentication method the Wallet Server uses with the OAuth Provider. If left null, defaults to CLIENT_SECRET_BASIC	private_key_jwt	No	No
additionalRequestParams	Additional parameters to include in requests to the OAuth Provider	{}	No	No

Authorization Server

Parameter	Description	Example value	Required	Localizable
identifier	An identifier for the Authorization Server	identos-authserver	Yes	No

Relationship	Description	Required
organization	The organization to which the Authorization Server belongs. See the example request above.	Yes
oauthClient	The OAuth Client entry for the Authorization Server. See the example request above.	Yes
oauthProvider	The OAuth Provider entry for the Authorization Server. See the example request above.	Yes

Sample Requests

Enroll an Authorization Server

curl -X PATCH '{{WS_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: en' \
  --data-raw '[
  {
    "op": "add",
    "path": "/oauth-client",
    "value": {
      "type": "oauth-client",
      "id": 1,
      "attributes": {
        "clientId": "authserver-client-id",
        "clientSecret": "authserver-client-secret",
        "baseUrl": "{{AUTH_SERVER_URI}}",
        "redirectUris": [
          "{{AUTH_SERVER_URI}}/transaction/callback"
        ]
      }
    }
  },
  {
    "op": "add",
    "path": "/oauth-provider",
    "value": {
      "type": "oauth-provider",
      "id": 1,
      "attributes": {
        "name": "Identos Auth Server",
        "clientId": "wallet-identos-clientid",
        "clientSecret": "wallet-identos-clientsecret",
        "issuerUri": "{{AUTH_SERVER_URI}}",
        "clientAuthenticationMethod": null, 
        "additionalRequestParams": {}
      }
    }
  },
  {
    "op": "add",
    "path": "/authorization-server",
    "value": {
      "type": "authorization-server",
      "id": 1,
      "attributes": {
        "identifier": "identos-authserver"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": 1
          }
        },
        "oauthClient": {
          "data": {
            "type": "oauth-client",
            "id": 1
          }
        },
        "oauthProvider": {
          "data": {
            "type": "oauth-provider",
            "id": 1
          }
        }
      }
    }
  }
]'

Important!

The value of the 'oauth-client' redirectUris in the above request must match the value specified in the oauth2-config.provider.authorize_endpoint parameter in the Authorization Server's application.config.

Get information about an Authorization Server

curl -X GET '{{WS_ADMIN_URI}}/authorization-server/1' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --header 'Accept-Language: en'

Update an Authorization Server entry

curl -X PATCH '{{WS_ADMIN_URI}}' \
  --header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
  --header 'ApiVersion: v1.0' \
  --header 'Authorization: {{WS_ADMIN_STATIC_TOKEN}}' \
  --data-raw '[
  {
    "op": "replace",
    "path": "/oauth-client/1",
    "value": {
      "type": "oauth-client",
      "id": 1,
      "attributes": {
        "clientId": "authserver-client-id",
        "clientSecret": "authserver-client-secret",
        "baseUrl": "{{AUTH_SERVER_URI}}",
        "redirectUris": [
          "{{AUTH_SERVER_URI}}/transaction/callback"
        ]
      }
    }
  },
  {
    "op": "replace",
    "path": "/oauth-provider/1",
    "value": {
      "type": "oauth-provider",
      "id": 1,
      "attributes": {
        "name": "Sotnedi Auth Server",
        "clientId": "wallet-sotnedi-clientid",
        "clientSecret": "wallet-sotnedi-clientsecret",
        "issuerUri": "{{AUTH_SERVER_URI}}",
        "clientAuthenticationMethod": null, 
        "additionalRequestParams": {}
      }
    }
  },
  {
    "op": "replace",
    "path": "/authorization-server/1",
    "value": {
      "type": "authorization-server",
      "id": 1,
      "attributes": {
        "identifier": "sotnedi-authserver"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": 1
          }
        },
        "oauthClient": {
          "data": {
            "type": "oauth-client",
            "id": 1
          }
        },
        "oauthProvider": {
          "data": {
            "type": "oauth-provider",
            "id": 1
          }
        }
      }
    }
  }
]'

Verify using the Wallet Application API: https://WALLET_API_SERVER/registry/authorization-servers

Notes on the OAuth Provider and OAuth Client

For OAuth Provider:

• The client_id, issuer_uri, and name must be unique.
• The value of issuer_uri must be the OAuth issuer base URL. i.e. OIDC provider must be discoverable from issuer_url/.well-known/openid-configuration

For OAuth Client:

• The client_id and base_url must be unique.
• The value of client_id shown in the request above will also be used when configuring the Wallet Web UI.

For both OAuth Client and Provider, there must be a reciprocal registration at the component which is the other party in the respective OAuth relationship.

note

For details on how to add localization options for an Authorization Server entry at the Wallet, refer to the Localization for the Wallet Server API chapter.