Authentication
Orchestrator > Orchestrator Server > Users & Authentication > Authentication
Use the Authentication dialog box to manage different remote authentication methods for Orchestrator users.
-
To add a new remote authentication method, click +Add New Server.
-
To view or modify the settings for an existing remote authentication method, click the Edit icon in the row of the existing method.
Orchestrator supports the following for remote authentication:
-
RADIUS
-
TACACS+
-
OAuth
-
JWT
-
SAML
Configure a RADIUS or TACACS+ Server
You need to configure the following when adding or modifying a RADIUS or TACACS+ server:
Field | Description |
---|---|
Attributes | Specify the privilege level/role by entering the attributes on the RADIUS or TACACS+ server: RADIUS: In the attributes section, select the cisco-av-pair and enter LOGIN:priv-lvl=[#] . Level 7 and above equates to admin role, level 6 and below is monitor. Optionally, for RBAC roles, enter LOGIN:rbac-roles=<RBAC role> , and for RBAC appliance access groups, enter LOGIN:rbac-aag=<RBAC aag> .TACACS+: In the custom attributes text box, enter role=<authorization level> . Valid authorization values are admin, monitor, manager. Optionally, for RBAC roles, enter rbac-roles=<RBAC role> , and for RBAC appliance access groups, enter rbac-aag=<RBAC aag> . |
Read-Write Privilege | RADIUS only: Lowest value at which a user has Read-Write privileges. This value must be the same as the value configured on the RADIUS server. |
Read-Only Privilege | RADIUS only: Lowest value at which a user has Read-Only privileges. This value must be the same as the value configured on the RADIUS server. |
Authentication Type | Select the authentication type that matches what is configured on the RADIUS or TACACS+ server. |
Default Role | If RBAC is enabled, you must specify a default role. |
Primary/Secondary Server | For each server in use, enter the IP address or hostname, port, and secret key of the RADIUS or TACACS+ server. |
Authenticate Using RADIUS or TACACS+
-
Select the access control protocol you want to use.
-
Under Servers, enter the information for a Primary server of that type. Entering a Secondary server is optional.
Field Description Authentication Order Whether to use the remote map or the local map first. The default is Remote first.
NOTE: If the Authentication Order field is set to Remote First, and if a password is configured for the CLI enable command, add a user named “enableuser” on the remote server and set the password to be identical to the one configured locally.Primary/Secondary Server IP address or hostname of the RADIUS or TACACS+ server. Secret Key String defined as the shared secret on the server. Read-Write Privilege Lowest value at which a user has Read-Write privileges. This value must be the same as the value configured on the RADIUS server. Read-Only Privilege Lowest value at which a user has Read-Only privileges. This value must be the same as the value configured on the RADIUS server. Authentication Type When configuring to use the TACACS+ server, select the type from the drop-down list that matches what is configured on the TACACS+ server.
Configure an OAuth Server
Orchestrator supports remote authentication via the OAuth 2.0 framework. Before configuring an OAuth server in Orchestrator, you must register Orchestrator as an application with your OAuth provider.
Prerequisites
-
The OAuth server must support OAuth 2.0 authorization codes, ID tokens, and (optionally) refresh tokens.
-
The ID token is used to get username, RBAC roles, and RBAC appliance access groups.
-
The refresh token can be checked periodically to ensure that the user is still authorized.
-
Depending on the OAuth server configuration, refresh tokens can be permanent or they can expire. If a token is revoked or expires, the user is forced to authenticate again.
Register Orchestrator as an App
Before adding an OAuth server in Orchestrator, register a new app on your OAuth server for Orchestrator. Provide the following details when registering the app:
Needed Information | Description |
---|---|
Application Type | Register Orchestrator as a Web App. |
Allowed Grant Types | Authorization code (required). Refresh token (optional). |
Redirect URL | Orchestrator endpoint to which the user is redirected after successful authentication, which should be https://<Orchestrator_domain_or_IP_address> /gms/rest/authentication/oauth/redirect. |
Configure OAuth Server Properties in Orchestrator
When adding a new OAuth server or modifying an existing server, configure the following fields in the Remote Authentication Server dialog box:
Field | Description |
---|---|
Name | Name to identify the server. This name is displayed on a button on the Orchestrator login page as an alternative method of authentication. |
Client ID | Client ID for the Orchestrator application that you created in your OAuth provider. |
Client Secret | Client secret for the Orchestrator application that you created in your OAuth provider. |
Scopes | OAuth 2.0 uses scope values, as defined in RFC 6749, to specify which access privileges are being requested for in Access Tokens. The default scopes for Orchestrator are openid, offline_access, and email. |
Authentication URL | The Issuer Identifier URL with the authentication request path appended. For example: https://<your-oauth-domain> /oauth2/v1/authorize. |
Token URL | The Issuer Identifier URL with the token path appended. For example: https://your-oauth-domain/oauth2/v1/token. |
Username key | The OAuth attribute to be sent as the username. If the username is an email address, use email. If any other key is used, ensure that it is mapped to the correct scope on the OAuth server. |
(Optional) Roles key | This field can be left with the default value, ec-roles, or you can enter a new key name, but the key name must match what is configured in your OAuth provider. This is a user claim sent in the ID token that maps to Orchestrator roles defined in Role Based Access Control (RBAC). For example, the OAuth server attribute userType maps to ec-roles, and the OAuth user in Orchestrator has userType = OverlayAdmin. NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in. |
(Optional) Appliance Access Group key | This field can be left with the default value, ec-aag, or you can enter a new key name, but the key name must match what is configured in your OAuth provider. This is a user claim sent in the ID token that maps to Orchestrator Appliance Access Groups defined in RBAC. For example, the OAuth server attribute department maps to ec-aag, and the OAuth user in Orchestrator has department = Asia-Admin. NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in. |
Default role | If RBAC is enabled, you must specify a default role. |
Configure a JWT Server
To begin JWT server configuration, the assigned admin must specify the following JWT configuration parameters:
-
Issuer ‘iss’
-
Auditor ‘aud’
-
expiration ‘exp
-
signature
-
user, role, and AAG
NOTE: See the following descriptions in the table below.
- Redirect URL based on successful authentication: https://<orchestrator_domainName> ?access_token=<token>&id_token=<token>&state=<state>&token_type=Bearer&expires_in=3596
Review the following diagram for more details about the workflow of JWT authentication.
Then, complete the following steps in Orchestrator:
-
Navigate to the Authentication dialog box in Orchestrator (Orchestrator > Users & Authentication > Authentication).
-
Click +Add New Server.
The Remote Authentication Server dialog box opens.
-
From the Type drop-down menu, select JWT, and then complete the following fields.
Field Description Name Name of your JWT provider. Cert/Signing Key HMAC or RSA public key used to verify the id_token. JWK URL URL that hosts the public certification. Validation Window Maximum amount of time (in minutes) that the expiration is found for the id_token before a new id_token is created. Issuer Issuer claim found in the id_token. Auditor Auditor claim found in the id_token. Username key This attribute is sent as the username. If the username is an email address, use email. If any other key is used, ensure that it is mapped to the correct scope on the OAuth server. Roles key This field can be left with the default value, ec-roles, or you can enter a new key name, but the key name must match what is configured in your JWT provider.
This is a user claim sent in the ID token that maps to Orchestrator roles defined in Role Based Access Control (RBAC). For example, the OAuth server attribute userType maps to ec-roles, and the OAuth user in Orchestrator has userType = OverlayAdmin.
NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in.Appliance Access Group key This field can be left with the default value, ec-aag, or you can enter a new key name, but the key name must match what is configured in your JWT provider.
This is a user claim sent in the ID token that maps to Orchestrator Appliance Access Groups defined in RBAC. For example, the JWT server attribute department maps to ec-aag, and the JWT user in Orchestrator has department = Asia-Admin.
NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in.Default role If RBAC is enabled, you must specify a default role. JWT token consuming URL URL of Orchestrator that remains the same.
Configure a SAML Server
Orchestrator supports SAML 2.0 integration, providing authentication and authorization of your credentials through an IdP (Identity Provider), SP (Service Provider), and a Principal. In this example, these are defined as follows:
-
IdP: Okta
-
SP: Orchestrator
-
Principal: A principal end user
SAML and Orchestrator Configuration
Use the following instructions to complete SAML and Orchestrator integration.
TIP: It is recommended to have Orchestrator open next to your Okta window while completing these instructions.
-
Sign in to your Okta account.
-
From the Okta Dashboard menu, click to expand Applications, and then click Applications.
-
Click Create App Integration, and then select SAML 2.0.
-
Click Next.
The General Settings dialog box appears.
-
Enter a name in the App name field.
-
Click Next.
The SAML Settings dialog box appears.
-
Sign in to Orchestrator and navigate to the Authentication dialog box (Orchestrator > Users & Authentication > Authentication).
-
Click +Add New Server.
-
Select SAML from the Type field.
-
Enter a Name for the server.
-
In Orchestrator, click the copy icon next to the ACS URL field.
A message at the bottom of the screen notifies you that text is copied to the clipboard.
-
Navigate to the Okta SAML Settings dialog box.
-
Paste the ACS URL into both the Single sign-on URL field and the Audience URI (SP Entity ID) field.
-
In Orchestrator, configure the following attributes on the Remote Authentication Server dialog box.
NOTE: For each attribute, you must click in the field and enter the text for the value. If you click Save without entering any text, no value is saved and the field remains empty.
Attribute Field Name Example Value Username Attribute ec-name Roles Attribute ec-roles Appliance Access Group Attribute ec-aag -
Navigate to the Okta SAML Settings dialog box, and in the Attribute Statements (optional) section, create the following attributes and corresponding values.
Name Example Value ec-name user.email ec-roles user.usertype ec-aag user.department NOTE: The roles that these claims map to in Orchestrator are configured and assigned to users on the RBAC tab in Orchestrator (Orchestrator > Orchestrator Server > Users & Authentication > Role Based Access Control (RBAC)).
-
Make sure the attribute names match in both applications.
NOTE: The attribute names you enter in the SAML provider (Okta) must exactly match the attribute names you created in Orchestrator, including character case.
-
Click Next.
-
Click Finish.
-
On the completed SAML settings page, click View SAML setup instructions.
-
Copy and paste the URLs from the following Okta fields into the corresponding Orchestrator fields.
Okta Field Orchestrator Field Identity Provider Single Sign-On URL SSO Endpoint Identity Provider Issuer Issuer URL X.509 Certificate IdP X.509 Cert -
In Orchestrator, click Save to save the changes you made on the Remote Authentication Server dialog box.
A message at the bottom of the screen notifies you that you have successfully created SAML server configuration.
The following table provides more details about the fields in Orchestrator.
NOTE: Okta supports assigning the attributes at the group level. Refer to either Okta documentation or your Okta administrator for more information.
Field | Description |
---|---|
Name | Any text value for your SAML account for identification purposes. |
Username Attribute | Retrieves the username from the SAML XML response. |
Issuer URL | Unique identifier of the issuer (for example: Okta, OneLogin). |
SSO Endpoint | Unique endpoint for the SAML application created on the IdP server. |
IdP X.509 cert | Certificate issued by IdP to verify and validate the response received from the IdP (Okta) server. |
ACS URL | Orchestrator endpoint needed for configuration on the IdP server. This is provided as a redirect URL after you are authenticated on the IdP server. |
(Optional) EdgeConnect SLO Endpoint | Endpoint used by IdP to initiate the logout request from Orchestrator to the IdP server. |
(Optional) IdP SLO Endpoint | Endpoint used by IdP to initiate the logout request from Orchestrator to the IdP server. Endpoint used by Orchestrator to initiate the logout request to IdP. |
(Optional) EdgeConnect X.509 Cert SLO | Certificate used by IdP to verify the Single Logout request initiated by Orchestrator to logout the IdP. |
(Optional) Roles Attribute | This field can be left with the default value, ec-roles, or you can enter a new key name, but the key name must match what is configured in your SAML provider. This is a claim sent to Orchestrator that maps to roles defined in Role Based Access Control (RBAC). NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in. |
(Optional) Appliance Access Group Attribute | This field can be left with the default value, ec-aag, or you can enter a new key name, but the key name must match what is configured in your OAuth provider. This is a claim sent to Orchestrator that maps to Orchestrator Appliance Access Groups defined in RBAC. NOTE: If roles and appliance access group keys are not provided, Orchestrator inspects its own configuration to determine the role and appliance access group for the user. If it does not find that information, the user is not allowed to log in. |
Default role | If RBAC is enabled, you must specify a default role. |