Configuring OIDC for users of Aporeto-protected applications
Before you begin
Before beginning the configuration, ensure the following.
- An Aporeto enforcer is installed on the host using the appropriate method:
- Aporeto recognizes the web application as a processing unit. (Check the Platform pane of the Aporeto web interface.)
- The web application accepts TCP connections.
- 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 imagine a user with the email
firstname.lastname@example.org trying to access a web application hosted at
example.com that is represented by a processing unit called
Adding Aporeto 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 Aporeto, 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/callbackto the fully qualified domain name of your web application. For example, if users reach the application at
https://www.example.com, the callback URL would be
- A domain name is required.
If your web application does not have one, append
.nip.ioto its public IP address. Example:
- Prefix the domain name with
httpseven if the application does not currently use TLS. The Aporeto enforcer will manage the encryption.
- If you want to expose the application on a port other than 443, specify the desired port.
- A domain name is required. If your web application does not have one, append
Client ID and client secret: The identity provider supplies a client ID and a client secret value. These values allow Aporeto to communicate with the identity provider. You'll need them in subsequent procedures.
Scopes: Though Aporeto 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. Note that all claim values must be returned as strings. Aporeto ignores arrays, booleans, and other types of values.
Confirming the identity provider's discovery endpoint
The OIDC specification does not require a discovery endpoint but Aporeto does. Most identity providers offer one. Confirm that your identity provider supports it as follows.
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
-- Azure Active Directory
Append your tenant ID to
All clients use the same path. Okta
The base URL is the same as the path in your browser when you access your account, without the
-adminstring. For example, if I access my Okta account at
https://dev-289699-admin.okta.com, my base URL is
/oauth2to the base URL. Then append the ID of your authorization server. If you have an Okta developer account, the ID is probably
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.
Confirm that your identity provider supports the discovery endpoint by issuing the following command.
It should return the JSON details of the OIDC configuration.
If you don't have curl installed, try replacing
wgetin the above command.
Navigating to the namespace of the processing unit
Open the Aporeto web interface and toggle recursive mode off.
Navigate to the namespace of the processing unit that represents the web server. Take a few moments to review its metadata. Determine the tag that you'd like to use to identify it later on.
Allowing the processing unit to initiate connections with the identity provider
If you have not enabled host protection or if your network policies already allow the enforcer to initiate connections with the identity provider, skip to the next section. Otherwise, complete the following steps.
Expand Network Authorization, select External Networks, and click the Create button.
Type the name of your identity provider in the Name field. You may also want to add a description and optionally propagate the external network to all children namespaces.
In the Networks tab, type the domain of your identity provider. If you completed the steps in Confirming the identity provider's discovery endpoint, you can retrieve this value via
tcpin the Protocols field,
443in Ports, and click Next.
ext:name=idpin the Tags field and click Create.
Select Network Policies and click the Create button.
Type an informative name in the Name field, for example
Select Outgoing traffic from the Network policy mode list box.
Select Propagate to child namespaces and click Next.
Type or paste the tag that identifies the processing unit of the web application in Source, click Next, and click Create.
SSH into the processing unit and execute the commands from the previous section.
export IDP_URL=<identity-provider-url> curl $IDP_URL/.well-known/openid-configuration
Open the Platform pane of the Aporeto web interface and confirm that the traffic is allowed. An example view follows.
Defining the HTTP resource
Expand the Service Authorization section, open the HTTP Resources pane, and click the Create button.
In the General tab, provide a name for the API exposed by the application. Example:
In the Endpoints tab, click the Add HTTP Resource button.
Type the name of the resource that authorized users should be allowed to access. Examples:
/*: all resources
/admin: access to the
Deselect the buttons of any HTTP methods that you don't want to allow on the resource.
Under Restrictions, specify the claims that must appear in the user's ID token using Aporeto's tag syntax. The values returned by the identity provider must be strings. Some examples follow.
Identity provider Scope requested Example claim value Aporeto tag all
You can include multiple tags connected by AND or OR to form a logical expression.
In the Tags tab, provide a tag for this HTTP Resource definition. For example,
Click the Create button.
Defining the service
Open the Services pane under Service Authorization and click the Create button.
In the General tab:
- Provide a name for the app. Example:
- Select HTTP as the Service Type.
- Click Next.
- Provide a name for the app. Example:
In the TLS Configuration tab, select one of the following.
Aporeto Public Signing CA: if you do not have a certificate signed by a trusted certificate authority (CA) you can use one signed by your Aporeto CA. Users will experience browser warning messages unless they manually configure their client to trust your Aporeto CA.
Custom Certificate: provide the certificate to be used for TLS. Include any intermediate CAs in the certificate. Because the Aporeto enforcer may need to terminate TLS, it also needs the private key of the certificate. Both files must be in PEM format.
In the HTTP Header Mappings tab you can configure Aporeto to pass claims from the ID token to the target application via the HTTP header.
In the User Authorization tab, select OpenID Connect and provide the following.
OIDC Provider URL: the URL of the identity provider. The Aporeto enforcer must be able to append
/.well-known/openid-configurationto this URL and receive the JSON details of the OIDC configuration. If you completed the steps in Confirming the identity provider's discovery endpoint, you can retrieve this value via
OAuth2 Client ID and OAuth2 Client Secret: the client ID and client secret given to Aporeto by the identity provider.
OIDC Callback URL: the fully qualified domain name of the target application. Example:
https://www.example.com. If you want to use a port other than 443, include the port. Example:
https://www.example.com:1443Note that your external network must have the alternate port open, as well.
Additional OIDC Scopes: Type
openidand press ENTER. Type the names of the additional scopes, pressing ENTER after each one. For example, if the identity provider supports refresh tokens and you would like to enable this feature, also include the
offline_accessscope. Refer to the Overview for more discussion of scopes.
You should request only scopes that return claims as strings. Scopes that return claims in boolean, array, or other formats are ignored by Aporeto.
In the Network tab, provide the following:
DNS Record: provide the DNS name of the application (required). Example:
example.com. If the application does not have a domain name, append
.nip.ioto its public IP address. Example:
IP Addresses: if you do not know the IP address or addresses, you can probably leave this blank. Aporeto can usually auto-discover the IP address or addresses of the application, except in certain circumstances, such as if your application sits behind an nginx Kubernetes ingress controller.
Service Port: the port that the actual application listens on, such as for connections from other services. For example, if the application is a container, the port that is open on the container. If the application is fronted by a load balancer, the port that the load balancer uses to connect to the application. Cannot be the same as the Public Application Port.
Exposed Port: if a load balancer or Kubernetes service fronts the application, the port that the load balancer listens on on behalf of the application. Typically 443.
Public Application Port: the port that the Aporeto enforcer should listen on on behalf of the application. Typically 443. It cannot be the same as the Service Port.
In Kubernetes/OpenShift deployments, ensure that the Kubernetes service in front of the container exposes the port specified in Public Application Port. You can use the following command to view the service YAML:
kubectl edit svc/<your-service-name>. The value of
portshould be identical to the value in the Public Application Port. If not, modify it to match and save your changes to update the Kubernetes service definition.
In the APIs & Processing Units tab, specify the following:
Exposed APIs: type the tag that you set in Define the HTTP resource. Example:
Processing Unit Selector: add
$identity=processingunitand press ENTER. Add
$type=Hostand press ENTER. Then type a tag that identifies the processing unit that represents the web application.
Click Next twice, skipping over the Advanced tab.
In the Tags tab, type a tag that identifies this service. For example,
Click the Create button.
Logging in as a user to verify
Open a new browser tab or private window.
Type the path to the application. In the example above, we used
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.
Return to the Platform pane of the Aporeto web interface.
Click to view the details of the successful flow from the external network to the application, including the ID token, as shown below.