IDENTITY-BASED MICROSEGMENTATION DOCUMENTATION

Authenticating users with OIDC

Overview

You can configure Microsegmentation 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 applications protected by Microsegmentation.

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

Before beginning the configuration, ensure the following.

  • Microsegmentation recognizes the web application as a processing unit. Open the Microsegmentation section of the Prisma Cloud web interface, navigate to the namespace of the web application, select Platform, and make sure you see it.

  • Review the tags of the processing unit representing the web application and locate one that identifies it uniquely.

  • The web application accepts TCP connections. Refer to Allowing access to web servers for instructions.

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

Identityprovider(IdP) Enforcer Application Browser 1 2 3 4 5 6 7 8 9 request credentials send credentials authenticate send ID token request target URL no IDtoken redirect to IdP URL redirect to callback URL request ID token redirect to target URL and   set cookie authorize forward request respond A box

In the examples below, we imagine a user with the email bjoliet@email.com trying to access a web application hosted at segment-doc-example.com that is represented by a processing unit called nginx-7bb7cd8db5-dgbxf.

Adding your app 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 URL: Sometimes referred to as a login redirect URI. Append aporeto/oidc/callback to the fully qualified domain name of your web application. For example, if users reach the application at https://segment-doc-example.com or http://segment-doc-example.com, the callback URL would be https://segment-doc-example.com/aporeto/oidc/callback

    • A domain name is required. You should obtain a domain name if you do not have one already. If you cannot obtain a domain name, you can try appending .xip.io or .nip.io to its public IP address. However, these services can be flaky and increase the chance of errors. Example: https://35.193.206.162.xip.io
    • Prefix the domain name with https even if the application does not currently use TLS. The enforcer will manage the encryption.
    • If you’ve exposed the application on a port other than 443, specify the port. Example: https://segment-doc-example.com:1443/aporeto/oidc/callback
  • Scopes: Though the enforcer sends the desired scopes in its request, some identity providers may ask you to identify the scopes during the configuration. If requested, supply the scopes to the identity providers.

Once you have added your application to the identity provider, it should give you a client ID and a client secret. Set these values in the CLIENT_ID and CLIENT_SECRET environment variables.

  • Client ID:

    export CLIENT_ID="0oannpib3fQEeUWzD4x6"
    echo $CLIENT_ID
    
  • Client secret:

    export CLIENT_SECRET="qcnc1ZFABmwmFwFZD_BAffNRFUn5aYQhvrx4XsxU"
    echo $CLIENT_SECRET
    

Confirming the identity provider’s discovery endpoint

The OIDC specification does not require a discovery endpoint but Microsegmentation does. Most identity providers offer one. Confirm that your identity provider supports it as follows.

  1. Obtain the identity provider’s address. 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/
    Azure Active Directory https://sts.windows.net/cd629cb5-2826-4126-82fd-3f2df5f5bc7b/ Append your tenant ID to https://sts.windows.net/
    Google https://accounts.google.com All clients use the same path.
    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 IDP_URL environment variable containing the identity provider’s URL. An example follows.

    export IDP_URL=https://dev-289699.okta.com/oauth2/default
    
  3. Set an environment variable containing just the domain name of the identity provider. An example follows.

    export IDP_DOMAIN=dev-289699.okta.com
    
  4. Confirm that 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.

    It should return the JSON details of the OIDC configuration.

Identifying your web application

  1. In the Microsegmentation section of the Prisma Cloud web interface, navigate to the namespace of the processing unit that represents the web application. Take a few moments to review its metadata. Determine the tag that you’d like to use to identify it.

  2. Set a PU_TAG environment variable containing the Microsegmentation tag that identifies the web application. An example follows.

    export PU_TAG="type=private-app"
    

Allowing the web application to initiate connections with the identity provider

  1. Set a MICROSEG_NS environment variable containing the Microsegmentation namespace of your application.

    export MICROSEG_NS=/acme/team-b/dev/private-app 
    
  2. Use the following command to create an external network representing your identity provider.

    cat <<EOF | apoctl api create externalnetwork -n $MICROSEG_NS -f -
    name: idp
    entries:
    - $IDP_DOMAIN
    protocols:
    - tcp
    ports:
    - "443"
    associatedTags:
    - ext:name=idp
    EOF
    
  3. Use the following command to create a network policy allowing your application to connect to the identity provider.

    cat <<EOF | apoctl api create networkaccesspolicy -n $MICROSEG_NS -f -
    name: allow-app-to-idp
    action: Allow
    applyPolicyMode: OutgoingTraffic
    logsEnabled: true
    subject:
    - - "\$identity=processingunit"
      - "$PU_TAG"
    object:
    - - ext:name=idp
    EOF
    
  4. The enforcer must be able to reach the identity provider’s discovery endpoint. SSH into the enforcer host or exec into the enforcer container and execute the commands from the previous section.

    export IDP_URL=<identity-provider-url>
    curl $IDP_URL/.well-known/openid-configuration
    
  5. In the Microsegmentation section of the Prisma Cloud web interface, select Platform, and confirm that the traffic is allowed. An example view follows.

idp allowed

Defining the HTTP resource

Next, we need to create an HTTP resource spec describing the kinds of requests your app will accept and the claims that must be in the user’s token.

  1. Determine how you want to identify the users that should be allowed to access your app. You request information about the user from the identity provider (scope) and it returns that information as a claim. The claim becomes a Microsegmentation tag.

    Identity provider Scope requested Example claim value Microsegmentation tag
    all email bjoliet@email.com email=bjoliet@email.com
    Google hd example.com hd=example.com

    TIP

    Microsegmentation supports logical expressions, allowing you to use multiple tags to identify users.

  2. Set a USER_TAG environment variable containing the Microsegmentation tag that identifies the allowed users.

    export USER_TAG="email=bjoliet@email.com"
    echo $USER_TAG
    
  3. Use the following command to create an HTTP resource spec that restricts access to the specified user. This spec allows GET requests to any resource in your web application (/*). You can optionally add additional methods or allow access only to certain endpoints.

    cat <<EOF | apoctl api create httpresourcespec -n $MICROSEG_NS -f -
    name: nginx
    endpoints:
    - URI: /*
      methods:
      - GET
      public: false
      allowedScopes:
      - - $USER_TAG
    associatedTags:
    - httpresourcespec:name=private-app
    EOF
    

Defining the service

  1. Create a USER_PORT environment variable to store the port used to access the web application. We recommend using 443. Otherwise, users will have to manually specify the port when they access your app.

    export USER_PORT=443
    

    TIP

    If your web application is running in Kubernetes, ensure that the port in its service definition has the value 443. You can open the service for editing via kubectl edit services <your-service-name> and modify the port to 443 if necessary.

  2. Create a APP_PORT environment variable containing the port that your web application is listening on. In Linux service deployments this is simply the port of the process. In container deployments this is the internal port of the container. If your web application is running in Kubernetes, this corresponds to the targetPort in its service definition.

    export APP_PORT=80
    
  3. Create an APP_DOMAIN environment variable containing the domain name that people use to access your web application.

    export APP_DOMAIN=segment-doc-example.com
    
  4. Create a APP_URL environment variable containing the full URL of your web application.

    export APP_URL=https://segment-doc-example.com
    
  5. Next, create a service definition. In the following example, we use private-app as the name of the service definition and we also add a Microsegmentation tag service:name=private-app. We request the email and openid scopes. You should change these values to fit your circumstances.

    cat <<EOF | apoctl api create service -n $MICROSEG_NS -f -
    name: private-app
    authorizationType: OIDC
    OIDCClientID: $CLIENT_ID
    OIDCClientSecret: $CLIENT_SECRET
    OIDCProviderURL: $IDP_URL
    OIDCCallbackURL: $APP_URL
    OIDCScopes: 
    - email
    - openid
    hosts:
    - $APP_DOMAIN
    port: $APP_PORT
    exposedPort: $USER_PORT
    selectors:
    - - $PU_TAG
      - \$identity=processingunit
    associatedTags:
    - service:name=nginx
    type: HTTP
    exposedAPIs:
    - - httpresourcespec:name=private-app
    EOF
    

TIP

If the identity provider supports refresh tokens and you would like to enable this feature, add the offline_access scope.

Logging in as a user to verify

  1. Open a new browser tab or private window.

  2. Type the path to the application. Example: https://segment-doc-example.com

  3. Click through the warnings to accept the certificate from the enforcer.

  4. The OIDC provider should pop up a browser window or tab requesting your login credentials.

  5. After authenticating to the OIDC provider, you should see the welcome page of the application.

  6. In the Microsegmentation section of the Prisma Cloud web interface, select Platform.

  7. Click to view the details of the successful flows, as shown below.

    Success OIDC

Troubleshooting

In the Microsegmentation section of the Prisma Cloud web interface, expand Monitor, and select Event logs. You can also use apoctl to collect Microsegmentation-related logs from the enforcer. See Troubleshooting enforcer.