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.
In this interaction type, users work in the web application.
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.
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.
In this interaction type, the manager sends API requests to agents to perform various operations.
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.
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.
In this interaction type, agents send reports on the API command execution and updates about serviced instance objects to the manager.
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 the ppem-agent.yml agent
configuration file using the agent.name
parameter.
api_key: The API key for connecting the
agent to the manager, which is specified in the
ppem-agent.yml agent configuration file
using the agent.manager.api_key
parameter.
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.
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.