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 is displayed.  You need to toggle this switch to ON.  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 `{kc_realms_path}/{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 {kc_realms_path}/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://datatracker.ietf.org/doc/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
}
----

There is the only access token returned by default. There is no refresh token returned and there is also no user session created
on the {project_name} side upon successful authentication by default. Due the lack of refresh token, there is a need to re-authenticate when access token expires,
however this does not mean any additional overhead on  {project_name} server side due the fact that sessions are not created by default.

Due to this, there is no need for logout, however issued access tokens can be revoked by sending request to the OAuth2 Revocation Endpoint described
in the <<_oidc-endpoints, OpenID Connect Endpoints>> section.