Signing In to the Console
Everyone who uses the HYPR AgentPass™ console signs in first. The role attached to their identity then decides what they can do. See Roles and Permissions.
There are two ways in:
- Sign in with SSO, through your own identity provider, using OpenID Connect (OIDC). This is how your team signs in day to day.
- Recovery administrator, a username and password held by the gateway itself. It exists so you can reach the console to set SSO up, and so you still have a way in if your identity provider is unreachable.
The sign-in page follows your tenant's default theme. See Themes.
Recovery Administrator
The recovery administrator signs in under or recovery administrator. The page describes it as a break-glass account, for IdP setup and emergencies, not everyday sign-in. Its credentials come from the invitation that set up your tenant, or from a password revealed in its place. See Inviting Tenant Administrators.
Repeated failed sign-ins temporarily pause recovery administrator sign-in, both for the account and for the source of the attempts. The pause lifts by itself, and successful sign-ins never count toward it. While it is in effect, the sign-in and password-change pages show Too many failed attempts.
Once SSO is working, keep the recovery administrator credentials in a protected break-glass location.
Connect the Console to Your Identity Provider
You configure console SSO in the console itself, with no restart and no configuration files. AgentPass works with any provider that supports OpenID Connect.
- Open Advanced → Gateway Settings, click the Authentication tab, and find Console SSO (OIDC).
- Register the redirect URI. The card shows the Redirect URI the gateway uses. Register that exact URI with your provider, as an allowed redirect for the application you create there. The provider refuses the sign-in otherwise.
- Enter the Issuer / auth-server URL. AgentPass reads the provider's published configuration from it, and fills in the authorization, token, userinfo, JWKS and end-session endpoints. Deployments behind a proxy that rewrites those addresses can enter the endpoint fields directly. If the provider is on your internal network, turn on Allow private network addresses. See Allow a Private Network Address.
- Enter the Client ID and Client secret of the registered application. The secret is stored encrypted and write-only, and saves independently of the other fields. A public client using PKCE needs no secret. Leave PKCE required on for providers that expect it.
- Set scopes.
openidis added for you. Addoffline_accessif sessions should renew without a fresh sign-in. See Session Length. - Map the claims that describe the person signing in. The claim settings are described in the following table.
- Click Save settings.
- Turn on Enable SSO. It becomes available once the issuer URL, client ID and client secret are saved, or the issuer URL and client ID with PKCE required on. AgentPass checks the provider before it enables SSO.
| Setting | What it does |
|---|---|
| Principal claim | Identifies the user, and keys their record in AgentPass. Choose something unique and stable per person, such as an employee ID or sub, not an address that can change |
| Display name claims | The claims whose values make up the name shown in the console, in order, joined with a space |
| Email claim | Where the email address lives. Kept separate from the principal, so notifications reach a mailbox even when the principal is not an address |
| Role claim | The claim that carries each person's roles or groups. See Populate Roles From Your Identity Provider |
Request only the scopes your provider permits for the application. A strict provider rejects the whole sign-in, not just the one scope. Decide on the principal claim before you roll out SSO. Changing it later strands the role assignments keyed to the old identifier.
After a successful sign-in, AgentPass lists the claims it observed in the token, so you can pick claim names from what your provider sends.
Populate Roles From Your Identity Provider
Set Role claim to the claim that carries each person's roles or groups, such as groups, or a nested path such as realm_access/roles. The default is hypr_role.
Then map the claim's values to roles, on each role's page. A person gets every role one of their values is mapped to. Matching is exact and case-sensitive. See Map Identity Provider Values to a Role.
Two rules settle a disagreement between the token and the console:
- Roles assigned in the console win. Later sign-ins do not change an administrator's direct assignment.
- Anyone else with no mapped value gets the default role, so a new person can sign in and be useful before a directory change lands.
On upgrade, AgentPass maps each existing role to its own name, exactly as written. People whose identity provider sends a role name in different capitalization get the default role until you add that value to the role.
Session Length
Maximum session length caps how long a console session lasts before the user signs in again. Sessions can end sooner if your provider issues no refresh token, which is why offline_access matters for providers that require it.
Compatibility and Troubleshooting
Leave these settings alone unless your provider needs them.
| Setting | When to use it |
|---|---|
| Client authentication method | How the client secret is sent. Several providers expect client_secret_basic |
| Token audience | When your provider verifies an audience value on the access token |
| Extra authorization params | Extra values your provider expects on the authorization request, such as an audience or prompt behavior |
| Token issuer override | When the provider's issuer value differs from the issuer URL, as in some proxied deployments |
If a sign-in fails, turn on Log login request/response bodies. The gateway records the exchange in its logs, with sensitive values redacted. Turn it off again once you are done.
Related
- Roles and Permissions — what each role can do once someone is signed in
- Gateway Settings — every tab of the settings page, including Authentication
- Themes — brand the sign-in page and the console