SAML Audience config update

docs/08.integration/04.saml/04.saml.md

@@ -5,35 +5,97 @@ taxonomy:
 slug: /integration/saml
 ---
 
-### SAML IDP Configuration
+## Setting Up Okta and NeuVector Integration
 
-To configure NeuVector to use Okta SAML IDP server, first, configure the SAML IDP server on the Okta site.
+This section describes how to configure Okta as a SAML 2.0 identity provider (IDP) for NeuVector. The setup steps are performed in Okta first, then in the NeuVector console.
 
-![Okta](okta.png)
+### Prerequisites
 
-1. Copy "SAML Redirect URI" from NeuVector SAML Setting page, paste it to Okta's single sign on url, recipient url and destination url fields.
-2. Assertion encryption: This field must be <strong>unencrypted.</strong>
-3. Attribute statements: Enter the email and username attributes.
-4. Group attribute statements: Enable this if group-based role mapping is required. The default attribute name that NeuVector looks for is NVRoleGroup. If other attribute name is used for the user's group membership, it can be customized in NeuVector's SAML Setting page.
+- An Okta Developer or Enterprise account with administrative privileges.
+- Administrator access to the NeuVector console.
+- The NeuVector SAML Redirect URI. Log in to NeuVector as an administrator, go to **Settings > SAML Settings** and copy the **SAML Redirect URI** shown at the top of the page.
+  - It has the form `https://<nv-console>:<port>/token_auth_server`, where `<nv-console>` and `<port>` are the address and port of your NeuVector console.
 
-Configure SAML settings in NeuVector UI console.
+### Okta Setup
 
-![SAML](saml1.png)
+1. Log in to the Okta Admin Console.
 
-Use "View Setup Instructions" button as shown in the following screenshot to locate following information, and copy them into NeuVector's SAML page. 
+2. In the left-hand navigation, expand **Applications** and click **Applications**, then click **Create App Integration**.
 
-1. Identity Provider Single Sign-On URL
-2. Identity Provider Issuer
-3. X.509 Certificate
-4. Specify group attribute name if non-default value is used.
+3. Select **SAML 2.0** as the sign-in method and click **Next**.
 
-![Setting](setting.png)
+![Okta sign-in method](okta_signin_method.png)
 
-After the user is authenticated, the proper role can be derived with group-based role mapping configuration. To setup group-based role mapping,
+4. On the **General Settings** step, enter a recognizable **App name**, for example `NeuVector SSO`, and click **Next**.
 
-1. If group-based role mapping is not configured or the matched groups cannot be located, the authenticated user will be assigned with the Default role. If the Default role is set to None, when group-based role mapping fails, the user is not able to login.
-2. Specify a list of groups respectively in Admin and Reader role map. The user's group attribute is piggybacked in the response after the user is authenticated. If the matched group is located, the corresponding role will be assigned to the user.
+5. On the **Configure SAML** step, map the Okta application to your NeuVector instance:
 
-#### Mapping Groups to Roles and Namespaces
+- **Single sign-on URL**: the NeuVector SAML Redirect URI copied in the prerequisites, `https://<nv-console>:<port>/token_auth_server`. Keep the setting **Use this for Recipient URL and Destination URL** checked.
+- **Audience URI (SP Entity ID)**: the same SAML Redirect URI, `https://<nv-console>:<port>/token_auth_server`.
+- **Name ID format**: `Unspecified`.
+
+![Okta SAML settings](okta_saml_config.png)
+
+:::note
+
+- NeuVector uses its SAML Redirect URI as both the assertion consumer service URL and the audience URI (SP entity ID); it is not configurable in the NeuVector console. Enter that same value in both Okta fields so the audience of the assertion matches what NeuVector expects.
+- Click **Show Advanced Settings** and confirm that **Assertion Encryption** is `Unencrypted`; NeuVector does not accept encrypted assertions. Leave **Response** and **Assertion Signature** set to `Signed`.
+
+:::
+
+6. On the **Feedback** step, select **This is an internal app that we have created** and click **Finish**.
+
+7. Configure the attribute statements so the SAML response carries the user's attributes back to NeuVector. On the application's **Sign On** tab, scroll to **Attribute Statements**, click **Show legacy configuration** and edit the statements below it:
+
+| Statement | Name | Name format | Value / Filter |
+| --------- | ---- | ----------- | -------------- |
+| Attribute Statements | `Email` | Unspecified | `user.email` |
+| Attribute Statements | `Username` | Unspecified | `user.firstName` |
+| Group Attribute Statements | `NVRoleGroup` | Unspecified | Matches regex `.*` |
+
+The group attribute statement is only required if group-based role mapping is used. `NVRoleGroup` is the attribute name NeuVector looks for by default. If you use a different attribute name for the user's group membership, enter that name in the **Group Claim** field of NeuVector's SAML Settings page.
+
+8. Open the **Assignments** tab, click **Assign > Assign to People**, and assign the users who should be able to log in to NeuVector.
+
+9. Return to the **Sign On** tab, scroll to the **SAML 2.0** section and open **Metadata details**. Collect the values needed by NeuVector:
+
+- **Sign on URL**: click **Copy** and save it.
+- **Issuer**: click **Copy** and save it.
+- **Signing Certificate**: click **Download** to save the certificate file, or click **Copy**.
+
+### NeuVector Setup
+
+1. Log in to the NeuVector console as an administrator and go to **Settings > SAML Settings**.
+
+![NeuVector SAML settings](nv_saml_settings.png)
+
+2. Fill in the fields with the information collected from Okta:
+
+- **Identity Provider Single Sign-On URL**: the Okta *Sign on URL*.
+- **Identity Provider Issuer**: the Okta *Issuer*.
+- **X.509 Certificate**: the complete text of the Okta *Signing Certificate*.
+- **Group Claim**: leave it empty to use the default `NVRoleGroup` attribute name, or enter the group attribute name configured in Okta.
+- **Default Role**: the role assigned to an authenticated user when group-based role mapping is not configured or no group matches. Set it to `None` to allow only users whose groups are mapped to a role.
+
+Every user needs a role, assigned either by the Default Role or by group-based role mapping. A user who ends up without a role cannot log in, even with the correct credentials.
+
+3. Optionally add group-based role mapping. Click **Add to Top** and enter a group name together with the **Global Role** and **Namespace Roles** to assign to its members.
+
+4. Check **Enable** at the bottom left of the page and click **Submit**.
+
+5. To test the integration, log out of NeuVector. The login screen shows a **Login with SAML** button that redirects to Okta for authentication.
+
+:::note
+**SAML Single Logout** is optional. Enable it only if your IDP supports SLO, and provide the **Identity Provider Single Logout URL** together with the single logout signing certificate and key.
+:::
+
+### Role Mapping
+
+After a user is authenticated, the role is derived from the group-based role mapping configuration:
+
+1. If group-based role mapping is not configured or the matched groups cannot be located, the authenticated user is assigned the Default role. If the Default role is set to None, the user is not able to log in when group-based role mapping fails.
+2. Specify the groups to map in the role map. The user's group attribute is piggybacked in the response after the user is authenticated. If a matched group is located, the corresponding role is assigned to the user.
+
+### Mapping Groups to Roles and Namespaces
 
 Please see the [Users and Roles](/configuration/users#mapping-groups-to-roles-and-namespaces) section for how to map groups to preset and custom roles as well as namespaces in NeuVector.

docs/08.integration/05.msazure/05.msazure.md

@@ -5,7 +5,7 @@ taxonomy:
 slug: /integration/msazure
 ---
 
-### Integrate with Azure AD SAML authentication
+## Integrate with Azure AD SAML authentication
 
 1. In the Azure management console, select the ”Enterprise applications" menu item in Azure Active Directory 
 
@@ -27,32 +27,37 @@ slug: /integration/msazure
 
 ![azure_config5](azure5.png)
 
-6. In the NeuVector management console, login as an administrator. Select “Settings" in the administrator dropdown menu at the top-right corner. Click SAML settings
+6. In the NeuVector management console, login as an administrator and go to **Settings > SAML Settings**
 
-![azure_config6](azure6.png)
+![NeuVector SAML settings](nv_saml_settings.png)
 
 7. Configure the SAML server as follows:
 
-+ Copy application's "Login URL" as the Single Sign-On URL.
-+ Copy "Azure AD Identifier" as the Issuer.
-+ Open downloaded the certificate and copy the text to X.509 Certificate box.
-+ Set a default role. 
-+ Enter the group name for role mapping. The group claim returned by Azure are identified by the "Object ID" instead of the name. The group's object ID can be located in **Azure Active Directory > Groups > Group name Page**. You should use this value to configure group-based role mapping in NeuVector.
+- Copy application's "Login URL" as the Single Sign-On URL.
+- Copy "Azure AD Identifier" as the Issuer.
+- Open downloaded the certificate and copy the text to X.509 Certificate box.
+- Set a default role. This is the role assigned to an authenticated user when no group matches the role map.
+- Add the group-based role mapping. Click "Add to Top" and enter the group together with the Global Role and Namespace Roles to assign to its members. The group claim returned by Azure are identified by the "Object ID" instead of the name. The group's object ID can be located in **Azure Active Directory > Groups > Group name Page**. You should use this value to configure group-based role mapping in NeuVector.
 
 ![OpenID5](openid5.png)
 
-Then Enable the SAML server.
+Every user needs a role, assigned either by the default role or by group-based role mapping. A user who ends up without a role cannot log in, even with the correct credentials.
 
-![azure_config7](azure7.png)
+Then check "Enable" at the bottom left of the page and click "Submit" to enable the SAML server.
 
-8. Copy the Redirect URL
+8. Copy the SAML Redirect URI shown at the top of the SAML Settings page with the "Copy to Clipboard" button. It has the form `https://<nv-console>:<port>/token_auth_server`, where `<nv-console>` and `<port>` are the address and port of your NeuVector console.
 
-![azure_config8](azure8.png)
+9. Return to the Azure management console to setup "Basic SAML Configuration". Paste the NeuVector SAML Redirect URI into both boxes:
 
-9. Return to the Azure management console to setup "Basic SAML Configuration". Copy NeuVector console's Redirect URL to both "Identifier" and "Reply URL" boxes
+- **Identifier (Entity ID)**: the audience URI of the NeuVector service provider.
+- **Reply URL (Assertion Consumer Service URL)**: the endpoint Azure AD posts the SAML response to.
 
 ![azure_config9](azure9.png)
 
+:::note
+NeuVector uses its SAML Redirect URI as both the assertion consumer service URL and the audience URI (SP entity ID); it is not configurable in the NeuVector console. Enter that same value in both Azure fields so the audience of the assertion matches what NeuVector expects.
+:::
+
 10. Edit "SAML Signing Certificate", changing the Signing Option to "Sign SAML response"
 
 ![azure_config10](azure10.png)
@@ -69,6 +74,6 @@ Then Enable the SAML server.
 
 ![azure_config13](azure13.png)
 
-#### Mapping Groups to Roles and Namespaces
+### Mapping Groups to Roles and Namespaces
 
 Please see the [Users and Roles](/configuration/users#mapping-groups-to-roles-and-namespaces) section for how to map groups to preset and custom roles as well as namespaces in NeuVector.

docs/08.integration/06.adfs/06.adfs.md

@@ -5,10 +5,11 @@ taxonomy:
 slug: /integration/adfs
 ---
 
-### Setting Up ADFS and NeuVector Integration
+## Setting Up ADFS and NeuVector Integration
+
 This section describes the setup steps in ADFS first, then in the NeuVector console.
 
-#### ADFS Setup
+### ADFS Setup
 
 1. From AD FS Management, right click on “Relying Party Trusts” and select “Add Relying Party Trust…”.
 
@@ -34,10 +35,14 @@ This section describes the setup steps in ADFS first, then in the NeuVector cons
 
 ![adfsSetup](adfs6.png)
 
-7. Enter the same SAML Redirect URI into the “Relying party trust identifier” field and click “Add”; then select “Next” to continue.
+7. Enter the same SAML Redirect URI into the “Relying party trust identifier” field and click “Add”; then select “Next” to continue. This identifier is the audience URI (SP entity ID) that AD FS puts in the audience restriction of the assertion.
 
 ![adfsSetup](adfs7.png)
 
+:::note
+NeuVector uses its SAML Redirect URI as both the assertion consumer service URL and the audience URI (SP entity ID); it is not configurable in the NeuVector console. Enter that same value in both the “Relying party SAML 2.0 SSO service URL” and the “Relying party trust identifier” fields so the audience of the assertion matches what NeuVector expects.
+:::
+
 8. Customize Access Control; then select “Next” to continue.
 
 ![adfsSetup](adfs8.png)
@@ -54,66 +59,69 @@ This section describes the setup steps in ADFS first, then in the NeuVector cons
 
 12. Select “Add Rule…” and choose “Send LDAP Attributes as Claims”; then select “Next”.  Name the rule and choose Active Directory as the Attribute store. Only Username outgoing claim is required for authentication if default role is set; else groups is needed for role mapping.  Email is optional.
 
-+ SAM-Account-Name -> Username
-+ E-Mail-Address -> Email
-+ Token-Groups – Unqalified Names -> groups
+- SAM-Account-Name -> Username
+- E-Mail-Address -> Email
+- Token-Groups – Unqalified Names -> groups
 
 ![adfsSetup](adfs11-12.png)
 
 13. Select “Add Rule…” and choose “Transform an Incoming Claim”; then select “Next”.  Name the rule and set the field as captured in the screenshot below.  The Outgoing name ID format needs to be Transient Identifier.
 
 ![adfsSetup](adfs12-13.png)
 
-#### NeuVector Setup
+### NeuVector Setup
+
+Log in to the NeuVector console as an administrator and go to **Settings > SAML Settings**, then fill in the following fields.
 
-1. Identify Provider Single Sign-On URL
+![NeuVector SAML settings](nv_saml_settings.png)
 
-+ View Endpoints from AD FS Management > Service and use “SAML 2.0/WS-Federation” endpoint URL.
-+ Example: https://<adfs-fqdn>/adfs/ls
+1. Identity Provider Single Sign-On URL
+
+- View Endpoints from AD FS Management > Service and use “SAML 2.0/WS-Federation” endpoint URL.
+- Example: https://<adfs-fqdn>/adfs/ls
 
 2. Identity Provider Issuer
 
-+ Right click on AD FS from AD FS Management console and select “Edit Federation Service Properties…”; use the “Federation Service identifier”.
-+ Example: http://<adfs-fqdn>/adfs/services/trust
+- Right click on AD FS from AD FS Management console and select “Edit Federation Service Properties…”; use the “Federation Service identifier”.
+- Example: http://<adfs-fqdn>/adfs/services/trust
 
 3. X.509 Certificate
 
-+ From AD FS Management, select Service > Certificate, right click on Token-signing certificate and choose “View Certificate…”
-+ Select the Details tab and click “Copy to File”
-+ Save it as a Base-64 encoded x.509 (.CER) file
-+ Copy and paste the contents of the file into the X.509 Certificate field
+- From AD FS Management, select Service > Certificate, right click on Token-signing certificate and choose “View Certificate…”
+- Select the Details tab and click “Copy to File”
+- Save it as a Base-64 encoded x.509 (.CER) file
+- Copy and paste the contents of the file into the X.509 Certificate field
 
 4. Group claim
 
-+ Enter the Outgoing claim name for the groups
-+ Example: groups
+- Enter the Outgoing claim name for the groups
+- Example: groups
 
 5. Default role
 
-+ Recommended to be “None” unless you want to allow any authenticated user a default role.
+Recommended to be “None” unless you want to allow any authenticated user a default role.
 
 6. Role map
 
-+ Set the group names of the users for the appropriate role.  (See screenshot example below.)
+Click **Add to Top** and enter the group name of the users together with the Global Role and Namespace Roles to assign to its members.
 
-![NVadfsSetup](nv_adfs1.png)
+Every user needs a role, assigned either by the default role or by the role map. A user who ends up without a role cannot log in, even with the correct credentials.
 
-#### Mapping Groups to Roles and Namespaces
+### Mapping Groups to Roles and Namespaces
 
 Please see the [Users and Roles](/configuration/users#mapping-groups-to-roles-and-namespaces) section for how to map groups to preset and custom roles as well as namespaces in NeuVector.
 
-### Troubleshooting
+## Troubleshooting
 
 1. ADFS SamlResponseSignature needs to be either MessageOnly or MessageAndAssertion.  Use Get-AdfsRelyingPartyTrust command to verify or update it.
 
 ![adfsTroubleshooting](nv_adfs2.png)
 
-
 2. Time synchronization between Kubernetes Nodes x ADFS Server
 
 For a successful authentication, the time between the Kubernetes nodes and the ADFS server needs to be the same to avoid time sync or clock drift issues. 
 
-It's recommended to use an [NTP server](https://en.wikipedia.org/wiki/Network_Time_Protocol), with equal time settings across all servers. 
+It's recommended to use an [NTP server](https://en.wikipedia.org/wiki/Network_Time_Protocol), with equal time settings across all servers.
 
 Please check and confirm that both ADFS and NeuVector hosts are synchronized and the potential delays do not exceed more than 10 seconds. You can use Linux and Windows commands to check dates, times and NTP server activity.
 
@@ -128,7 +136,6 @@ You can reload the auth times by disabling and enabling again the config in the
 Once the setting has been re-enabled, you can try to log in with an ADFS user. If it works, this confirms the issue was due to a time synchronization error between Kubernetes nodes and the ADFS Server. 
 :::
 
-
 3. SAML characters must be case sensitive in NeuVector UI
 
 Attribute names are case sensitive. Make sure any SAML attribute name configured here is an exact match to the application configuration. SAML must point to the correct URL to authenticate. 
@@ -143,7 +150,7 @@ The SAML settings need to match the following configuration:
 
 | Setting | Value |
 | ------- | ----- |
-| Identify Provider Single Sign-On URL | Requires HTTPS protocol |
+| Identity Provider Single Sign-On URL | Requires HTTPS protocol |
 | Identity Provider Issuer | Requires HTTP protocol |
 | ADFS SamlResponseSignature | Needs to be either MessageOnly or MessageAndAssertion |
 
@@ -154,4 +161,3 @@ These settings need to be validated on your ADFS server and in the NeuVector UI.
 The selected certificate needs to be valid and correctly generated, including its `CA Root` and `Intermediate Certificates`. You can generate them using your trusted certificate authority, Windows or an automation tool such as [LetsEncrypt](https://letsencrypt.org/).
 
 If any of these parameters are incorrect, you will receive an `Authentication Failed` error when you try to log in to NeuVector with an ADFS user using SAML authentication.
-