Scope Verification Service
The OneWelcome Identity Platform assumes that the scope verification service is available as an external application exposing the HTTP endpoint for scope verification.
This service can either be a small component that translates the API to a vendor-specific API or it can be a middleware layer that already has access to the implementation.
The REST API that the OneWelcome Identity Platform uses is described in the API specification.
Scope verification service properties can be configured on the admin console, in the Scope services section:
| Property | Example | Description |
|---|---|---|
| Scope verification enabled | true | Indicates if REST-based scope verification is enabled. When disabled, the user is authorized without verifying scopes. |
| Service endpoint | http://service.endpoint.com | External REST endpoint that is called during scope verification. |
| Username | username | Basic auth username for the scope verification service endpoint. |
| Password | secret | Basic auth password for the scope verification service endpoint. |
| Verification failed endpoint | http://verification.failed.endpoint.com | Default endpoint the user is redirected to when it is not authorized for a scope. |
| Authentication endpoint | http://authentication.endpoint.com | Endpoint the user is redirected to when its authentication level is not sufficient. |
REST scope verification service API
This section describes the API that the OneWelcome Identity Platform expects when the REST scope verification service is used.
The scope verification service endpoint accepts POST requests with application/json or application/json;charset=UTF-8 as the content-type header. Optionally, it can be protected with basic authentication. The request body is a JSON object containing the following properties:
| Property | Example | Description |
|---|---|---|
| user_id | onegini-user-1234 |
Unique identifier of the user |
| external_identity | external-identity-abcd |
Identifier of the user as issued by the identity provider during authentication |
| scopes | [{"id": "read", "service_endpoint": "https://service.example.com"}] |
An array containing scopes to verify |
The endpoint is expected to return the 200 OK status code along with a JSON object with the following properties:
| Property | Example | Description |
|---|---|---|
| verification_result | SUCCESS |
possible values are SUCCESS or FAILURE |
| unauthorized_scope | read |
It is only present when the value of verification_result is FAILURE. It contains the scope for which verification failed. |
Example request
POST /verify-scope HTTP/1.1
Host: service.example.com
Content-Type: application/json;charset=UTF-8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
{
"user_id": "onegini-user-1234",
"external_identity": "external-identity-abcd",
"scopes": [
{"id": "read", "service_endpoint": "https://readservice.example.com"},
{"id": "write", "service_endpoint": "https://writeservice.example.com"}
]
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"verification_result": "FAILURE",
"unauthorized_scope": "read"
}
