Skip to main content

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

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
}
}
}
}
}
]'

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.

Request Attributes

The API call shown above 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 this request are described below according to the entity to which they belong.

OAuth Client

ParameterDescriptionExample valueRequiredLocalizable
clientIdAn identifier for the OAuth Client (the Authorization Server in this case) to use with the Walletauthserver-client-idYesNo
clientSecretAn secret for the OAuth Client (the Authorization Server in this case) to use with the Walletauthserver-client-secretYesNo
baseUrlThe base URL of the OAuth Client{{AUTH_SERVER_URI}}YesNo
redirectUrisAn array which defines a list of the URIs that the Wallet will permit redirects to on behalf of this client{{AUTH_SERVER_URI}}/transaction/callbackNoNo

OAuth Provider

ParameterDescriptionExample valueRequiredLocalizable
nameA human-readable name for the OAuth ProviderIdentos Auth ServerYesYes
clientIdThis value is used to identify the Wallet Server with the OAuth Provider (the Authorization Server in this case)wallet-identos-clientidYesNo
clientSecretA secret the Wallet Server uses with the OAuth Provider (the Authorization Server in this case)wallet-identos-clientsecretYesNo
issuerUriThe base URL of the OAuth Provider{{AUTH_SERVER_URI}}YesNo
clientAuthenticationMethodThe authentication method the Wallet Server uses with the OAuth Provider. If left null, defaults to CLIENT_SECRET_BASICprivate_key_jwtNoNo
additionalRequestParamsAdditional parameters to include in requests to the OAuth Provider{}NoNo

Authorization Server

ParameterDescriptionExample valueRequiredLocalizable
identifierAn identifier for the Authorization Serveridentos-authserverYesNo
RelationshipDescriptionRequired
organizationThe organization to which the Authorization Server belongs. See the example request above.Yes
oauthClientThe OAuth Client entry for the Authorization Server. See the example request above.Yes
oauthProviderThe OAuth Provider entry for the Authorization Server. See the example request above.Yes

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.