Identity-Based Microsegmentation Guide
LAST UPDATED: November 8, 2021

Configure an identity provider

Overview

You can configure Microsegmentation Console to authenticate users against any OpenID Connect (OIDC) identity provider. Examples include Google, Okta, Azure Active Directory, Yahoo, Auth0, and many others.

Integration with an OIDC identity provider gives your users single sign-on access to the Microsegmentation Console.

Microsegmentation uses the OIDC authorization code flow with a confidential client, as described in the OIDC 1.0 specification.

You can use scopes to request basic information about the user from the identity provider. If the user consents to the requested scopes, the identity provider returns the information to Microsegmentation as claims in an ID token. The claims in the ID token allow you to control which users can gain access.

All identity providers should support the following list of scopes and claims.

  • profile scope requests the following claims:

    • name
    • family_name
    • given_name
    • middle_name
    • nickname
    • preferred_username
    • profile
    • picture
    • website
    • gender
    • birthdate
    • zoneinfo
    • locale
    • updated_at
  • email scope requests the following claims:

    • email
    • email_verified
  • address scope requests the address claim

  • phone scope requests the following claims:

    • phone_number
    • phone_number_verified

Each identity provider supports additional scopes and claims. Refer to the documentation of the identity provider to learn more. Request only scopes that return claims as string, array, or boolean values. Microsegmentation ignores other types of claim values.

NOTE

The OIDC sequence requires a browser and is not suitable for authenticating applications.

Before you begin

Familiarize yourself with the following sequence, particularly the bolded URLs. Hover over the numbers for additional details.

Identityprovider(IdP) Console Client 1 2 3 6 request credentials send credentials authenticate send ID token login request redirect to IdP URL redirect to callback URL request ID token exchange 5 send Microseg token 4 7 A box

Once the user obtains an Microsegmentation token containing the claims from the identity provider, they can use it to access:

  • Microsegmentation Console web interface
  • apoctl

Microsegmentation checks the policy you’ve defined against the claims in the Microsegmentation token to determine whether to allow the user access.

Adding Microsegmentation to the identity provider

While OIDC is a standard, each identity provider provides a different web interface. This section guides you through the setup at a high level.

NOTE

Many identity providers orient their offerings towards developers. Good news! With Microsegmentation, you won’t need to write any code to integrate with the identity provider.

  • Web application: Identity providers often support a variety of application types. If prompted, select web application.

  • Callback URLs: Supply the identity provider with the following list of allowed callback URLs. Identity providers sometimes refer to these as redirect URIs or login redirect URIs.

    • https://<your-console-domain>/popup/oidc-verify: replace <your-console-domain> with the domain name of your Microsegmentation Console
    • http://localhost:65332
  • Client ID and client secret: The identity provider supplies a client ID and a client secret value. These values allow Microsegmentation to communicate with the identity provider. Store these values in a safe place. You’ll need them in subsequent procedures.

  • Scopes: Though Microsegmentation sends the desired scopes in its request, some identity providers may ask you to identify the scopes during the configuration. If so, supply the scopes to the identity provider. For a detailed discussion of scopes, refer to the Overview.

Confirming the identity provider’s discovery endpoint

Most identity providers offer a discovery endpoint, although this is optional in the specification. Microsegmentation requires the discovery endpoint. Confirm that your identity provider supports it as follows.

  1. Obtain the identity provider’s URL. Your identity provider should make this value easy to obtain, but we provide some tips below.

    Provider Example Discussion
    Auth0 https://dev-bzp6k6-2.auth0.com/
    Google https://accounts.google.com All clients use the same path.
    Microsoft Azure Active Directory https://sts.windows.net/cd629cb5-2826-4126-82fd-3f2df5f5bc7b/ Append your tenant ID to https://sts.windows.net/
    Okta https://dev-289699.okta.com/oauth2/default The base URL is the same as the path in your browser when you access your account, without the -admin string. For example, if I access my Okta account at https://dev-289699-admin.okta.com, my base URL is https://dev-289699.okta.com. Append /oauth2 to the base URL. Then append the ID of your authorization server. If you have an Okta developer account, the ID is probably /default
  2. Set an environment variable containing the identity provider’s URL. An example follows. Replace <identity-provider-url> with the identity provider’s URL before issuing the command.

    export IDP_URL=<identity-provider-url>
    
  3. Check if your identity provider supports the discovery endpoint by issuing the following command.

    curl $IDP_URL/.well-known/openid-configuration
    

    TIP

    If you don’t have curl installed, try replacing curl with wget.

  4. Confirm that the command returns the JSON details of the identity provider’s configuration.

Adding the identity provider to Microsegmentation

  1. In the Microsegmentation Console web interface, expand Authentication Sources and select OIDC Providers.

  2. Click the Create button to add a new identity provider.

  3. Type the name of the identity provider in the Name field.

    TIP

    If you have more than one identity provider, users must manually type this name to identify their identity provider. It is case sensitive.

  4. In the Endpoint field, add the identity provider’s URL. If you completed the steps in Confirming the identity provider’s discovery endpoint, you can retrieve this value via echo $IDP_URL

  5. Paste the client secret in the Client Secret field and the client ID in the Client ID field.

  6. Type the requested scopes in the Scopes field, pressing ENTER after each one. At a minimum, you must have openid. If the identity provider supports refresh tokens and you would like to enable this feature, also include the offline_access scope. For more detail on scopes, refer to the Overview. These will allow you to identify the user and determine whether or not to authorize them.

  7. To set this as the default identity provider, select Use this provider as the default.

    IMPORTANT

    We recommend setting at least one identity provider as the default.

  8. To add values of claims to the subject field of the Microsegmentation token, type the name of the scope in the Subject field, pressing ENTER after each one. Examples follow.

    Scope Claim Description
    profile family_name Adds the user’s last name to the Microsegmentation token.
    email email Adds the user’s email address to the Microsegmentation token.
    groups* groups Adds the value for the groups claim to the Microsegmentation token. The type of value returned by the identity provider varies. Configure your identity provider to return an array or a string, as Microsegmentation ignores booleans.

    * Not available from all identity providers.

  9. Click Create.

Creating an API authorization

  1. Expand Namespace Settings, click Authorizations, and click the Create button.

  2. Type a name for the policy.

  3. If you want the user to have access to all of the children of the current namespace, select Propagate to child namespaces.

  4. If you do not want this policy to be visible in the child namespaces, select Hide propagation to child namespaces.

  5. Type @auth:realm=oidc in the Subject field and press ENTER. Then type the Microsegmentation tag that defines the value of the claim that must appear in the user’s Microsegmentation token. Some examples follow.

    Identity provider Scope requested Example claim key or value Microsegmentation tag
    all email bjoliet@email.com @auth:email=bjoliet@email.com
    Google hd example.com @auth:hd=example.com
    Microsoft Azure Active Directory groups groups:1e94a453-2727-47f6-b59e-d86df3494312 @auth:groups:1e94a453-2727-47f6-b59e-d86df3494312=true
    Microsoft Azure Active Directory tid tid:9188040d-6c67-4c5b-b112-36a304b66dad @auth:tid:9188040d-6c67-4c5b-b112-36a304b66dad=true
    Okta groups groups:your-org @auth:groups:your-org=true

    TIP

    You can include multiple tags connected by AND or OR to form a logical expression.

  6. Select the namespace that you want to allow the user to access from the Target Namespace list box.

  7. Click Next.

  8. If you want to require the user to attempt their login from a certain subnet or subnets, specify the subnet or subnets in the List of authorized subnets field.

  9. Click Next.

  10. Select the roles that the user should have.

  11. Click Create.

  12. Congratulations! The user should now be able to click Sign in with OIDC to access the Microsegmentation Console web interface and use apoctl auth oidc to log into apoctl.