Authenticating users with OIDC
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](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth).
You can use [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) 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](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). 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.
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.
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 Console web interface, selectPlatformin the side navigation menu, navigate to the namespace of the web application, and make sure you see it.
- Review the tags of the processing unit representing the web application and locate one that identifies it uniquely.
Familiarize yourself with the following sequence, particularly the bolded URLs. Hover over the numbers for additional details.
In the examples below, we use:
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.
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://microseg-website.com or http://microseg-website.com, the callback URL would be https://microseg-website.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://188.8.131.52.xip.io
- 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.
export CLIENT_ID="0oannpib3fQEeUWzD4x6" echo $CLIENT_ID export CLIENT_SECRET="qcnc1ZFABmwmFwFZD_BAffNRFUn5aYQhvrx4XsxU" echo $CLIENT_SECRET
Confirming the identity provider’s discovery endpoint
- Obtain the identity provider’s address. Your identity provider should make this value easy to obtain, but we provide some tips below.ProviderExampleDiscussionAzure Active DirectoryAll clients use the same path.OktaThe 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
- Set an IDP_URL environment variable containing the identity provider’s URL. An example follows.export IDP_URL=https://dev-289699.okta.com/oauth2/defaultSet an environment variable containing just the domain name of the identity provider. An example follows.export IDP_DOMAIN=dev-289699.okta.comIdentifying your web application
Allowing the web application to initiate connections with the identity provider
- In the Microsegmentation Console 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.
- Set a PU_TAG environment variable containing the Microsegmentation tag that identifies the web application.In the following example, we use the tag we used in the Hipster Shop tutorial.export PU_TAG="app=frontend"
- Set an ENFORCER_NS environment variable containing the Microsegmentation namespace of the enforcer for your application.This will be a grandchild-level namespace, either the namespace of your cluster or your host.export ENFORCER_NS=/acme/aws-dev/k8s-clusterUse the following command to create an external network representing your identity provider.cat <<EOF | apoctl api create externalnetwork -n $ENFORCER_NS -f - name: idp entries: - $IDP_DOMAIN associatedTags: - externalnetwork:name=idp propagate: true EOFUse the following command to create a network ruleset allowing your application to connect to the identity provider.cat <<EOF | apoctl api create networkrulesetpolicy -n $ENFORCER_NS -f - name: allow-app-to-idp subject: - - \$identity=processingunit - "$PU_TAG" outgoingRules: - action: Allow object: - - externalnetwork:name=idp protocolPorts: - tcp/443 propagate: true EOFThe enforcer must be able to reach the identity provider’s discovery endpoint.SSH into the enforcer host or one of the cluster nodes and execute the commands from the previous section.export IDP_URL=<identity-provider-url> curl $IDP_URL/.well-known/openid-configurationIt should return the details of your OIDC configuration in JSON form.Defining the HTTP resourceNext, 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.
Defining the service
- 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.Microsegmentation supports logical expressions, allowing you to use multiple tags to identify users.
- Set a USER_TAG environment variable containing the Microsegmentation tag that identifies the allowed users.export USER_TAG="email@example.com" echo $USER_TAGUse the following command to create an HTTP resource spec that restricts access to the specified user.cat <<EOF | apoctl api create httpresourcespec -n $ENFORCER_NS -f - name: nginx endpoints: - URI: /* methods: - GET public: false allowedScopes: - - $USER_TAG associatedTags: - httpresourcespec:name=private-app propagate: true EOF
- 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.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=80Create an APP_DOMAIN environment variable containing the domain name that people use to access your web application.export APP_DOMAIN=microseg-website.comCreate a APP_URL environment variable containing the full URL of your web application.export APP_URL=https://microseg-website.comNext, create a service definition.cat <<EOF | apoctl api create service -n $ENFORCER_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 propagate: true EOFLogging in as a user to verify
- Open a new browser tab or private window.
- Type the path to the application.
- Click through the warnings to accept the certificate from the enforcer.
- The OIDC provider should pop up a browser window or tab requesting your login credentials.
- After authenticating to the OIDC provider, you should see the welcome page of the application.
- Open the Microsegmentation Console web interface, selectPlatformin the side navigation menu, and navigate to the namespace of the web application.
- Click to view the details of the successful flows, as shown below.
Recommended For You
Recommended VideosRecommended videos not found.