In this example, we will use External Authentication with our API. I used a multi-node/high availability (HA) Authentication Broker installed on an AWS server and have Google API Services as the Identity Provider.
- Reference Articles
- Infrastructure Setup
- Broker Configuration
- Identity Provider Configuration
- End to End Testing
I chose to setup in AWS. For others, you can setup your broker wherever you want and take care of the internal/external URL and internet traffic accordingly.
For this use case, I have a Boomi Authentication Broker installed on an AWS server. Similar to a Molecule installation, the HA Broker will consist of two or mode nodes (EC2 instances). These nodes are backed by a shared network storage. You can setup an EFS drive (Running a Molecule on Amazon Web Services) or you can setup an NFS server that simply shares an EBS volume via NFS.
Network, Security Groups, and Local Working directories should be configured similar to how you might configure a Molecule (Linux Hardening Best Practices).
Refer to the Reference Guide for complete installation instructions. At a high level, just like a Molecule install, from one of the node, install the Broker software onto the NFS. Then, setup the systemd on each node to automatically start the Broker service on each node.
Like a Molecule, the cluster must also be behind a load balancer. In this example, the AWS ELB will terminate SSL(443) and forward traffic to an internal port (9093). We will allow AWS to manage the SSL certificates, as most systems implicitly trust AWS certificates. The ELB should be configured to check for a 200 return code, from each node, on /auth/. Note: Take note of the trailing "/". This is in contrast to using the /_admin/status page on a Molecule or Atom).
Internal URL and /etc/hosts
There must be a common network alias that can be used on each node, to define that node's network address. Each node, must be able to reference this alias, to identify the network adapter on which the software will accept requests. This is similar to how we use localhost to identify the loopback address on each machine. In this example, we use the alias "networkhost." In the /etc/hosts file on each machine, this alias refers to the network address of that specific machine.
There are only a few items to configure on the Broker itself. To access the External Authentication page:
- Switch to the API Management UI from the platform
- Go to the Authentication tab and select External
- Select the Broker you wish to configure, and update the following settings
By default, the Broker's host name will be set to that of the node on which you ran the install. You should change this to be the name of the Broker itself.
Under Cluster Nodes, you must add an entry for each node under your load balancer. You can use host names or aliases that are known to the internal network. These do not need to be publicly addressable. In my example, I add "atom01" and "atom02," which resolve locally within my network.
The Internal URL should be set using the "networkhost" alias above. Again, in my example, because the ELB terminates SSL, internally, I will use the http protocol, and I will be using the port 9093 e.g. the Internal URL is "http://networkhost:9093".
For External URL, I have configured a public DNS entry to reference my load balancer, and my AWS certificates are based on this domain e.g. the External URL is "https://example.boomi.cloud".
To know if your Auth Broker was setup correctly, you should be able to go to: <<external_URL>>/auth e.g. "https://example.boomi.cloud/auth" in the browser and see a keycloak page like the one below:
Note: my AWS certificate is publicly trusted, so it is not necessary to specify it here. This way, I can leverage the AWS Certificate Manager to replace it, without having to update my configuration.
Identity Provider Configuration
Google OpenID is used as the identity provider.
Configuring Google (1/2)
- Go to https://console.developers.google.com
Note: for any actions within the Google tools, if you are currently managing multiple Google accounts, you may need to open an "incognito" page and log into a single account at a time
- On left, select "Credentials"
- Click "Create Credentials then select "OAuth Client ID"
- Select "Web Application" as the application type
- Give the client ID any name e.g. "Google OAuth client for use with Boomi Broker"
- Copy the "Client ID" and "Client Secret" somewhere convenient, you will need these when you configure the Authentication Source in the next steps
Configuring Authentication Source
- Go to the AtomSphere API Management page
- Go to "Authentication", select "External"
- Click "New" then "Authentication Source" to create a new authentication source
- Add an Authentication Source Name e.g. "google_openid" and choose Identity Provider Type as "OpenID Connect v1.0"
- Click "Save"
- Change the Authentication Broker to the broker you installed above
- Uncheck the "OpenID Implicit Flow" option and leave "OpenID Authorization Code Flow" checked
Identity Provider Settings
- Go to the Identity Provider tab in the authentication source
- Give an alias e.g. "google_openid"
- Authentication URL is https://accounts.google.com/o/oauth2/v2/auth
- Token URL is https://www.googleapis.com/oauth2/v4/token
- Enter the Client ID and Client Secret copied from "Configuring Google (1/2)", step 5
- In default Scopes, add "openid"
Note: you can add other scopes as long as it is in accordance with how google's OAuth 2.0 and OpenID works
- Prompt Type is "Unspecified"
- Copy the Redirect URL for the next steps and click "Save"
Configure Google (2/2)
- Return to the Google Developer Console again and edit (pencil icon) the OAuth Client
- Update "Authorized redirect URIs" with the copied value of the "Redirect URL" captured in "Identity Provider Settings", step 8
- Click "Save"
Test Identity Provider Configuration
- On the Authentication Source, click "Test Identity Provider Configuration" button at bottom
- This should pop up a new browser tab, and you must select/login with your Google account
- You should get confirmation that the "Authorization Token" was correctly generated, both on the new tab and back on the authentication source page
End to End Testing
We're assuming you have a working API with some REST/SOAP endpoint setup prior to the external authentication setup. If you do not, set one up to make sure it is working properly and returning some response when called. Deploy your API component(s) and related processes.
Shared Web Server Settings
- On the Atom/Runtime that will be hosting the Web Service/API, navigate to "Atom Management"
- Go to "Shared Web Server"
- Set the "API Type" to "Advanced" and "Authentication Type" to "External Provider"
Note: In cloud environments, this must be enabled by the cloud owner
This is to setup your API to use the external authentication
- Switch to API Management
- Go to the "APIs" page
- Select "Manage" next to the API component you are testing, you'll be taken to the "Deployments" page
- Under "Authentication", select "Atom Controlled"
- In the "Configure an Authentication Source" window that appears, change "Authentication Type" to "External authentication provider"
- Under "Authentication Source" select the source created in the "Configuring Authentication Source" steps
Copy the following "Connection Information" somewhere convenient:
- Token URL
- Client ID
- Under "Contracts", select "No Contracts"
- In the dialog that appears, click "Add Contract" and give the contract a name e.g. "unlimited"
Note: for this example, we will not restrict our test API
- Go to "Applications" page, and click "Create an Application"
- Fill in the "Name," "Owner," and "Email" fields
- Under the "Authorized APIs" tab, click "Authorize an API" and search for your API component
- Click "Choose a Contract," click to highlight the "unlimited" contract made in step 9, and click "Choose this Contract"
- Copy the API Key somewhere
You can build test process with a new HTTP Client connector to call the API you deployed.
There are some specific fields you will need for the HTTP connection:
Authentication Type: OAuth 2.0
Grant Type: Authorization Code
Client ID: "Api Management" step 7c, Client ID
Client Secret: leave empty
Authorization Token URL: "Api Management" step 7a, Authentication URL
Scope: leave empty
Access Token URL: "Api Management" step 7b, Token URL
Access Token: Click "Generate" to get a token. If prompted, select the Google account you used to create the OAuth credentials above. You should see a token was created and stored
Add an additional "X-API-KEY" header and set as the value copied from "API Management", step 14.
Run the test process in "Test Mode" against any run time and you should get the expected response when it was working without external authentication. In my example, I am using the public Test Cloud, to consume a service hosted on a Private Cloud.