keycloak-scim/server_admin/topics/clients/oidc/service-accounts.adoc

[[_service_accounts]]

==== Service Accounts

Each OIDC client has a built-in _service account_ which allows it to obtain an access token.
This is covered in the OAuth 2.0 specifiation under <<_client_credentials_grant,Client Credentials Grant>>.
To use this feature you must set the <<_access-type, Access Type>> of your client to `confidential`.  When you do this,
the `Service Accounts Enabled` switch will appear.  You need to turn on this switch.  Also make sure that you have
configured your <<_client-credentials, client credentials>>.

To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {project_name} admin console for this client.
In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
Remember that you must have the roles available in Role Scope Mappings (tab `Scope`) of this client as well, unless you
have `Full Scope Allowed` on. As in a normal login, roles from access token are the intersection of:

* Role scope mappings of particular client combined with the role scope mappings inherited from linked client scopes
* Service account roles

The REST URL to invoke on is `/auth/realms/{realm-name}/protocol/openid-connect/token`.
Invoking on this URL is a POST request and requires you to post the client credentials.
By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication.
You also need to use the parameter `grant_type=client_credentials` as per the OAuth2 specification.

For example the POST invocation to retrieve a service account can look like this:

[source]
----

    POST /auth/realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials
----
The response would be this https://tools.ietf.org/html/rfc6749#section-4.4.3[standard JSON document] from the OAuth 2.0 specification.

[source]
----

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":60,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "refresh_expires_in":600,
    "id_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "not-before-policy":0,
    "session_state":"234234-234234-234234"
}
----

The retrieved access token can be refreshed or logged out by an out-of-bound request.