Using TEOS Authentication service
Additional APIs are required to be used along with TEOS API in case TEOS API Consumer doesn't have its own authentication service and needs TEOS Authentication service. Read more
TEOS Authentication service (we also refer to it as AuthServer) is used to authenticate users for TEOS Platform components including TEOS API.
OAuth Endpoints
OAuth 2.0 standard endpoint implementation details are described below. Custom endpoint references can be found here.
Discovery Endpoint
Discovery Endpoint
GET
/.well-known/openid-configuration
The discovery endpoint can be used to retrieve metadata about the AuthServer - it returns information like the issuer name, key material, supported scopes etc. See the spec for more details.
The discovery endpoint is available via /.well-known/openid-configuration relative to the base address, e.g.:
https://auth.coreledger.net/.well-known/openid-configuration
You can use the IdentityModel client library to programmatically access the discovery endpoint from .NET code. For more information check the IdentityModel docs.
Authorize Endpoint
Authorize Endpoint
GET
/connect/authorize
The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.
Query Parameters
Name | Type | Description |
---|---|---|
client_id* | identifier of the client | |
request | String | instead of providing all parameters as individual query string parameters, you can provide a subset or all of them as a JWT |
request_uri | String | URL of a pre-packaged JWT containing request parameters |
scope* | String | one or more registered scopes |
redirect_uri* | String | must exactly match one of the allowed redirect URIs for that client |
response_type |
| |
response_mode | String |
|
state | String | auth server will echo back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection. (recommended) |
nonce | String | auth server will echo back the nonce value in the identity token (this is for replay protection) Required for identity tokens via implicit grant. |
prompt | String |
|
code_challenge | String | sends the code challenge for PKCE |
code_challenge_method | String |
|
login_hint | String | can be used to pre-fill the username field on the login page |
ui_locales | String | gives a hint about the desired display language of the login UI |
max_age | String | if the userโs logon session exceeds the max age (in seconds), the login UI will be shown |
acr_values | String | allows passing in additional authentication related information - identityserver special cases the following proprietary acr_values:
|
If the error page is returned, it is always the same, and stating
Sorry, there was an error: unauthorized_client
Reason for such an error could be: ClientId, scopes or redirect_uri are sent to the /authorize endpoint not like they are defined in the Discovery Service. Exact reason could be determined by CoreLedger support.
AuthServer supports a subset of the OpenID Connect and OAuth 2.0 authorize request parameters. For a full list, see here.
Example:
(URL encoding removed, and line breaks added for readability)
You can use the IdentityModel client library to programmatically create authorize requests .NET code. For more information check the IdentityModel docs.
Token Endpoint
Token Endpoint
POST
/connect/token
The token endpoint can be used to programmatically request tokens. It supports the password
, authorization_code
, client_credentials
, refresh_token
and urn:ietf:params:oauth:grant-type:device_code
grant types. Furthermore the token endpoint can be extended to support extension grant types.
Request Body
Name | Type | Description |
---|---|---|
client_id* | String | client identifier (required โ Either in the body or as part of the authorization header.) |
client_secret | String | client secret either in the post body, or as a basic authentication header |
grant_type | String |
|
scope | String | one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued. |
redirect_uri | String | required for the |
code | String | the authorization code (required for |
code_verifier | String | PKCE proof key |
username | String | resource owner username (required for |
password | String | resource owner password (required for |
acr_values | String | allows passing in additional authentication related information for the
|
refresh_token | String | the refresh token (required for |
device_code | String | the device code (required for |
AuthServer supports a subset of the OpenID Connect and OAuth 2.0 token request parameters. For a full list, see here.
Example:
In the case of wrong request it returns the problem
(Form-encoding removed and line breaks added for readability)
You can use the IdentityModel client library to programmatically access the token endpoint from .NET code. For more information check the IdentityModel docs.
UserInfo Endpoint
UserInfo Endpoint
GET
/connect/userinfo
The UserInfo endpoint can be used to retrieve identity information about a user (see spec).
The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the openid scope is required).
Example:
You can use the IdentityModel client library to programmatically access the userinfo endpoint from .NET code. For more information check the IdentityModel docs.
Introspection Endpoint
Introspection Endpoint
POST
/connect/introspect
The introspection endpoint is an implementation of RFC 7662.
It can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries). The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the ApiResource
.
Example:
A successful response will return a status code of 200 and either an active or inactive token:
Unknown or expired tokens will be marked as inactive:
An invalid request will return a 400, an unauthorized request 401.
You can use the IdentityModel client library to programmatically access the introspection endpoint from .NET code. For more information check the IdentityModel docs.
Revocation Endpoint
Revocation Endpoint
POST
/connect/revocation
This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification (RFC 7009).
Request Body
Name | Type | Description |
---|---|---|
token* | String | the token to revoke |
token_type_hint | String | either |
Example:
You can use the IdentityModel client library to programmatically access the revocation endpoint from .NET code. For more information check the IdentityModel docs.
End Session Endpoint
The URL for the end session endpoint is available via the discovery endpoint.
End Session Endpoint
GET
/connect/endsession
The end session endpoint can be used to trigger single sign-out (see spec).
To use the end session endpoint a client application will redirect the userโs browser to the end session URL. All applications that the user has logged into via the browser during the userโs session can participate in the sign-out.
Query Parameters
Name | Type | Description |
---|---|---|
id_token_hint | String | When the user is redirected to the endpoint, they will be prompted if they really want to sign-out. This prompt can be bypassed by a client sending the original id_token received from authentication. This is passed as a query string parameter called |
post_logout_redirect_uri | String | If a valid |
state | String | If a valid |
Example:
You can use the IdentityModel client library to programmatically create end_session requests .NET code. For more information check the IdentityModel docs.
Specific endpoints
Refer to the Auth Server Swagger
Rate limits
When developing integration with TEOS Authentication service you should take into account the limits described in Rate limits of TEOS API. Those limits are defined per tenant and shared by all TEOS Platform components.
Last updated