# Authentication

## Overview

The ProcessMaker IDP API uses OpenID Connect for authentication. [OpenID Connect (OIDC)](https://www.keycloak.org/docs/latest/server_admin/#sso-protocols) is an authentication protocol that is an extension of OAuth 2.0.

Below is OpenID Connection configuration base URL to get details about all security endpoints:

```
https://{idp-keycloak}/auth/realms/{realm}/.well-known/openid-configuration
```

The ProcessMaker IDP REST API uses Keycloak's implementation of OIDC.  For more info about Keycloak, please refer to the [official documentation](https://www.keycloak.org/docs/latest/server_admin/#sso-protocols).

## Retrieve an Access Token

Keycloak Server OIDC URI endpoints are relative URLs. The ProcessMaker IDP REST API supports grant types that Keycloak supports. By default, this API uses password credentials as the grant type.

{% hint style="info" %}
Prior to sending an initial request to Keycloak for an authentication token, ensure that you have the following:

* Username and password when using password credentials as the grant type
* Your IDP instance's Client Secret
  {% endhint %}

Keycloak can obtain the client ID from a request in either of the following ways:

* The `client_id` parameter in the query (described in Section 2.2 of the [OAuth 2.0 Specification](https://tools.ietf.org/html/rfc6749))
* `client_id` as a query parameter that you supply in your request

All endpoints require the Keycloak realm name ProcessMaker IDP configures for your instance. If you do not know your instance's realm name, consult with your Customer Service Manager or ProcessMaker Support.

### `auth` Endpoint

Consider the following base URL example which uses the `auth` endpoint:

```
https://{idp-keycloak}/api/realms/{realm}/protocol/openid-connect/auth
```

### `token` Endpoint

## Obtain Keycloak temporary code to subsequently grant access to the IDP instance.

<mark style="color:green;">`POST`</mark> `https://{idp-keycloak}/api/realms/{realm-name}/protocol/openid-connect/token`

## Obtain Keycloak temporary code to subsequently grant access to the IDP instance.

<mark style="color:green;">`POST`</mark> `https://{idp-keycloak}/api/realms/{realm-name}/protocol/openid-connect/token`

Use the `token` endpoint in the base URL to obtain a temporary code from Keycloak in the Authorization Code Flow or to obtain tokens via the Implicit Flow, Direct Grants, or Client Grants.

#### Path Parameters

| Name                                          | Type   | Description                                                                                                          |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>  | String | Keycloak client ID. Described in Section 2.2 of the [OAuth 2.0 Specification](https://tools.ietf.org/html/rfc6749)). |
| grant\_type<mark style="color:red;">\*</mark> | String | Grant type to authenticate with Keycloak. By default use `password` grant type.                                      |
| username<mark style="color:red;">\*</mark>    | String | Username provided by ProcessMaker IDP.                                                                               |
| password<mark style="color:red;">\*</mark>    | String | Password corresponding with `username` parameter.                                                                    |

#### Path Parameters

| Name                                          | Type   | Description  |
| --------------------------------------------- | ------ | ------------ |
| client\_id<mark style="color:red;">\*</mark>  | String | UahPzgNf9wYx |
| grant\_type<mark style="color:red;">\*</mark> | String | 82BXeyjecKyx |
| username<mark style="color:red;">\*</mark>    | String | Fpwz43Y8GiNT |
| password<mark style="color:red;">\*</mark>    | String | BCvDSDkD1ky9 |

After receiving the Keycloak token, place it into the header for subsequent requests to your IDP instance with the following key and corresponding value:

* **Key:** `Authorization`
* **Value:** `Bearer {Keycloak-token}`

Refresh the token with the following `POST` request in subsequent calls:

```
POST https://{idp-instance}/token/refresh
```

### `userinfo` Endpoint

Use the `userinfo` endpoint in the base URL for the Authorization Code Flow to turn a temporary code into a token:

{% code fullWidth="false" %}

```
https://{idp-keycloak}.processmaker.com/api/realms/{realm-name}/protocol/openid-connect/userinfo
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://processmaker.gitbook.io/idp/idp-developer/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.