7.5. Authentication and Authorization Operation Scheme #
There are three interaction types that require authentication and authorization during the manager’s operation:
All interactions are carried out via the HTTP or HTTPS protocol depending on the PPEM parameters.
7.5.1. User → Manager #
In this interaction type, users work in the web application.
7.5.1.1. User → Manager: Authentication #
The user sends a POST /v1/sessions API request to the manager’s endpoint to obtain access and refresh tokens for subsequent operations. The API request contains user credentials.
In the basic scenario, credentials are checked against the repository. When using LDAP authentication, credentials are first checked against the directory service, then if they are not found, they are checked against the repository.
7.5.1.2. User → Manager: Authorization #
Upon successful authentication, subsequent HTTP/HTTPS requests from users to the manager include the Authorization header, where the Bearer keyword is followed by a space and the access token text. For example:
headers: Content-Type: application/json Authorization: "Bearer eyJhbG..."
The granted access is determined using the role-based access control (RBAC) model in accordance with the roles assigned to the user:
You can assign roles to PPEM users directly or through PPEM groups they are members of.
You can assign roles to LDAP users only through PPEM groups they are members of.
To add an LDAP user to a PPEM group, the administrator must map the distinguished name (DN) of the user’s LDAP group to the PPEM group name. The user is then automatically added to the PPEM group when logging in to the web application.
The user group composition is periodically checked against the LDAP server and updated if necessary.
For more information about mapping LDAP groups to PPEM groups, refer to Chapter 25.
7.5.2. Manager → Agent #
In this interaction type, the manager sends API requests to agents to perform various operations.
7.5.2.1. Manager → Agent: Authentication #
The manager sends a POST /v1/sessions API request to the agent’s endpoint to obtain access and refresh tokens for subsequent operations. The API request is made via the URL for connecting the agent to the manager from the repository and contains two parameters:
name: The agent name from the repository.api_key: The API key for connecting the agent to the manager from the repository.
7.5.2.2. Manager → Agent: Authorization #
Upon successful authentication, subsequent HTTP/HTTPS requests from the manager to agents include the Authorization header, where the Bearer keyword is followed by a space and the access token text. For example:
headers: Content-Type: application/json Authorization: "Bearer eyJhbG..."
The agent verifies the authenticity of the manager’s access token. To do this, the agent generates a token based on the known values of the name and api_key parameters. If the generated and received tokens match, the authentication is successful. If the authenticity is confirmed and the requested endpoint is found, further work is allowed.
7.5.3. Agent → Manager #
In this interaction type, agents send reports on the API command execution and updates about serviced instance objects to the manager.
7.5.3.1. Agent → Manager: Authentication #
The agent sends a POST /v1/sessions API request to the manager’s endpoint to obtain access and refresh tokens for subsequent operations. The API request is made via the URL for connecting the agent to the manager, which is specified in the ppem-agent.yml agent configuration file using the agent.manager.url parameter. The API request contains two parameters:
name: The agent name, which is specified in theppem-agent.ymlagent configuration file using theagent.nameparameter.api_key: The API key for connecting the agent to the manager, which is specified in theppem-agent.ymlagent configuration file using theagent.manager.api_keyparameter.
7.5.3.2. Agent → Manager: Authorization #
Upon successful authentication, subsequent HTTP/HTTPS requests from the agent to the manager include the Authorization header, where the Bearer keyword is followed by a space and the access token text. For example:
headers: Content-Type: application/json Authorization: "Bearer eyJhbG..."
The manager verifies the authenticity of the agent’s access token. To do this, the manager generates a token based on the known values of the name and api_key parameters. If the generated and received tokens match, the authentication is successful. If the authenticity is confirmed and the requested endpoint is found, further work is allowed.
The granted access is determined by the rules specified in the PPEM code for how the agent should access manager resources.
7.5.4. Lifetime of Access and Refresh Tokens #
The lifetime of access and refresh tokens is limited. It can be specified in the ppem-manager.yml manager or ppem-agent.yml agent configuration file using the jwt.lifetime.access and jwt.lifetime.refresh parameters.
When the access token expires, the manager or agent starts responding to the token owner with the “401 Unauthorized” error and the “ERR_AUTH_TOKEN_EXPIRED” code, for example:
{
"error":{
"code":"ERR_AUTH_TOKEN_EXPIRED",
"title":"token is expired"
}
}
To get a new access token, the token owner must send a PUT /v1/sessions API request to the endpoint with the refresh token that was received along with the expired access token. This results in new access and refresh tokens that can be used for further work.
If the refresh token has also expired, the token owner must reauthenticate.