In the enterprise integration, Federated IdP model is usually preferred over a direct IdP integration, a couple of reasons:
- Federated IdP model allows the application layer to adhere to a single contract/structure/protocol defined by the application IdP.
- Able to encapsulate the variations from External IdPs such as the protocol used (SAML 2.0 or OIDC), different profile/group naming attributes.
- Good for maintenance. by having Federated IdP, we will have all the users (local or federated) to be registered under the application Okta, and will be benefited from the out of the box Okta capability such as session auditing, IP whitelisting etc.
In this write up, we are going to use OKTA as our application IdP with an OIDC application and Federated IdP setting up. The user will initiate the Oauth 2.0 authorisation endpoint from a SPA application and will be granted idToken and accessToken upon authentication. The accessToken should have the authorization claims that’s going to be referred by the application layer for a user policy control. E.g. the admin API should only allow access to a user with admin group.
For the ease of explanation, we will split them into multiple section
- OIDC application setup on Application IdP OKTA
- Federated IdP setup with SAML 2.0, with configuration to achieve profile synchronization
- SPA client code for OIDC authentication/lifecycle handling
- Server side accessToken and jwks integration
1.0 Okta Oidc Application Setup
- Okta’s Federated IdP feature builds on top of Oidc, first we create a SPA type Oidc Application (Federated IdP is not restricted to SPA type).
- Okta allows free account creation for development purposes. If you have not created one, you can get your free OKTA instance from here.
- First ensure you are on the developer console.
1. Click the “Applications” menu and navigated to the “Application” page
2. Click on “Add Application” and select “Single-Page App”
3. Change the name to “Application OIDC”
4. As we are going to use the Angular framework in this demo, change all the urls related paths to “http://localhost:4200”, click “Done” to complete setup
5. OKTA’s SPA application supports implicit and public client authorization grant with PKCE only. The later one is always preferred due to better security. (refers to here for more read up)
- The next is the group creation, go to “User” menu then “Groups”, add a few groups (Admin, Premium and Basic) and assign the the a test user.
- OIDC with PKCE requires CORS handshake to be configured, go to “API” menu then “Trusted Origins”
— Add “http://localhost:4200” as trusted origin - The next is to create custom claim of “groups” under the accessToken, go to “API” menu then “Authorization Server”, click on the “default” authorization server then go to the “Claims” tab
— Add a claim called “groups” with all groups type
- We can then test the custom claim from the “Token Preview” tab
2.0 Federated IdP setup
- In this demo, we are going to create another Okta account to simulate the External IdP. Similar steps as above
- In this External IdP we will create a SAML 2.0 applications
2.1 SAML 2.0 Application creation on External IdP
- To create a SAML 2.0 type of application, we need to switch to the classic UI mode
- Go to “Applications” page and click on “Add Application”, select “Create New App” instead of the existing template.
- Select Platform as “Web” and “SAML 2.0” as the sign on method
- Key in the App name, E.g. “Client SAML 2.0 Application”
- For the SAML settings, as we do not have any SSO url generated yet, we will put some dummy value (http://replaceme.localhost)
- For SAML profile, add a few default profiles such as userName, firstName, lastName and email and for group attributes add a “groups” attribute that capture all assigned groups (This step is important for profile sync from External to Application IdP)
- Upon completion of application creation, under the created application, click on “View Setup Instruction”.
- It should navigate you to a page with the SAML 2.0 configuration for “Client SAML 2.0 Application” which consists of Identity Provider Single Sign-On URL, Identity Provider Issuer, and the X.509 Certificate.
2.2 Register the External “Client SAML 2.0 Application” on Application IdP
- Back to Application IdP (developer console), navigate to “User” then click on “Social & Identity Provider”
- Click on “Add Identity Provider” > “Add SAML 2.0 IdP”
- Key in the name “Client SAML 2.0” with IdP username as “idpuser.subjectNameId”
- JIT settings is required for profile and group sync
- Select “Full sync of groups” with SAML Attributes of “groups”
- Complete the SAML protocol settings by filling up with the SAML 2.0 configuration for the “Client SAML 2.0 Application”
- Upon creation, another set of SAML 2.0 configuration will be created which consists of Assertion Consumer Service URL and Audience URI.
2.3 Complete SAML 2.0 Application Setup on External IdP
- The SAML 2.0 configuration generated from the Application IdP is required to complete the setup from External IdP
- Navigate back to the “Client SAML 2.0” and edit the profile
- Replace the “Single sign on URL” with the “Assertion Consumer Service URL” from Application IdP. Replace the “Audience URI (SP Entity ID)” with the “Audience URI” from the Application IdP
- The resultant setting should be as such
3.0 Client Integration
- An angular project is created to perform demo/testing of the Okta Oidc federated flow (code and page).
- oidc-client is the library used (here) and the federated idp authorization flow is initiated with a custom query param of “idp” with the value of Federated IdP’s id registered in the Application IdP (reference)
- To test the Federated IdP setup above, we first navigate to the page and create a test profile
- Fill up the contents
Name => Anything
Oidc Client Id => “Application OIDC”’s client id
Issuer => Okta Authorization Server (by default is ${okta-domain}/oauth2/default
Scope => openid profile email
Okta url => leave it
Federated IdP Entries =>Name = Anything, Id = Id from Federated IdP entry created from step 2.2
- Select the profile created as Active Profile
- Before testing, we need to add the page url (https://blackjackyau.github.io/okta-oidc-angular-page) as a qualified redirected url in the “Application OIDC” Application from the Application IdP (both login and logout redirected URI)
- Navigate back to the login page and you should able to see login button as such. Before clicking the login button, do ensure you have logged out in both Application and External IdP
- Click on the Fed Login button should navigate you to the External IdP, key in credential to login
- Upon success authentication, observed the access token JWT claim, we should see only see the “Everyone” under the groups claim
- Why ? It is because we have not set up the groups for the External IdP.
- Complete the setup of Group (Admin, Premium and Basic) and assign to the test user.
- Redo the login and you should be seeing a set of groups been assigned to the user’s access token groups claim
4.0 Server Integration
- Not going to into the implementation details (in future maybe)
- Recommend to use openid well-known discovery method to discover the JWT verifications key (public key)
${okta-authorization-server-url}/.well-known/openid-configuration
(E.g. here) - Goto “jwks_uri” url to retrieve JWKS public keys for access token JWT verification
- Should be able to leverage on some oidc libraries available out there
5.0 [Advance] Dedicated claims for federated groups
Depending on the setup and requirement, it is possible for the group assignment to come from the local or federated IdP. Sometimes, to fulfill the requirements on auditing and etc, we will need to be able to identify the the groups influenced by federated IdP. To achieve this, we will create a dedicated profile attribute and claim for the groups coming from federated IdP.
5.1 Create custom attribute “external group” in default OKTA User Profile
- Go to menu “User” then navigate to “Profile Editor”
- Click on “User(default)” profile
- Add new attribute called “external_groups” of string array type to represent groups coming from federated IdP
- Alternatively, add new attribute called “external_groups_as_string” of string type to represent groups coming from federated IdP in a string format
5.2 Profile mapping of Federated User Profile to OKTA User profile
- Go to menu “User” then navigate to “Social and Identity Provider”
- Click on the Federated IdP registered earlier (Client SAML 2.0)
- Click on “Configured” and navigate to “Edit Profile and Mappings”, and you should be navigated to the Federated User Profile
- Add an attribute of call “groups” to match the SAML 2.0 profile generated from the client IdP
5. Go to “Mappings” and complete the profile mapping as such
appuser.groups → external groups
Arrays.toCsvString(appuser.groups) → external_groups_as_string
6. Save and apply updates
5.3 Testing
- in our preview setup, we are using the “Full sync of groups” type of Group Assignment (meaning groups will be fully derived from Federated IdP)
- For a hybrid setup, change it to “Add user to missing groups”
- From the Federated IdP, assign only “Admin” and “Premium” group to the test user (no “Basic”)
- Test the federated login again on the angular application and you should able to see the access token’s claims as such where “groups” and the effective groups and “external_groups” is the groups coming from Federated IdP
