Note: For the SSO R12.7 Client OAuth Federation partnership to work with the SSO OpenIDC provider a bug fix DE320033 was required. If you need to get this working it is best to open a support ticket and quote that reference number.
In a prior article we setup an SSO OpenIDC Provider, and then used it from the Apache mod_openidc client.
Here we describe setting up the client side SSO Partnership Federation OAuth connecting to the remote SSO OpenIDC Provider setup in the prior article.
1) Prerequisites:
For our setup, we need an existing SSO OpenIDC Provider already setup, and we need a SSO Policy Server and SSO Access Gateway to build up our Client side.
SSO OpenIDC Provider Configured for domain www.example.com
Policy Server R12.7
Access Gateway R12.7
Note: Ideally the SSO OpenIDC Provider would have their own Policy Server & Agent Gateway machine, and we would setup the OpenIDC Client on a separate Policy Server and Agent Gateway machine. However that wasn't available to us at the time, but we are able to get our Agent Gateway machine to services URL's from both www.example.com and www.demo.com, map them to different webagents, and the configuration of the federation setup for SSO OpenIDC Client fortunately didn't overlap with the setting for the Provider side (we did save on needing to export one certificate, and it made debugging tracing the calls in Ag a bit tricky).
2) Test Case & Example
After completing our setup this is how the example works. We have a client www.demo.com that will authenticate via OpenIDC provider www.example.com and then give access to the local resource.
SSO OpenIDC Client : http://www.demo.com/
SSO OpenIDC Connect Provider : http://www.example.com/affwebservices/secure/secureredirect
We access URL in the the openIDC client side: https://www.demo.com/affwebservices/public/oauthtokenconsumer/cad7017955?AuthzServerID=www-example-com
Which forwards the request to the SSO OpenIDC Provider at www.example.com, which then asks for credentials to login to the www.example.com domain:
https://www.demo.com/affwebservices/public/oauthtokenconsumer/cad7017955?AuthzServerID=www-example-com
After login to www.example.com we are redirected back to ww.demo.com /affwebservices/public/oauthtokenconsumer/ which process the client side of the federated authentication, makes a back channel call back to www.example.com to get the userinfo attributes, and then processes the client login logs us into the demo.com domain and creates the SMSESSION header.
We are then redirected to the open page http://www.demo.com where SPS then authenticates the request and passes it onto the backend server (in this case Ag forwards the request to localhost:81, where the IIS server is running, and we have default.aspx page setup to dump headers). And so the page we see is:
And here is the fiddler trace of the above transaction :
3) Create SSO Federation Entities
First for the OAuth Client setup we need two federation entities a Remote OAuthz Server and a Local OAuth Client.
Using the "Create Entity" button on the Partnership/Entities page we create a remote www-example-com entity and a local www-demo-com entity. The entities are fairly simple and most of the settings come from our prior setup of the CA SSO OpenID Connect Provider where we have already defined the client & provider URL's :
The Remote OAuth Authz Server setup :
The Local OAuth Client setup :
4) SSO Federation Partnership Setup
We now create a partnership with our two entities. On the Partnerships page we press the "Create Partnership" button.
Which drives us through the wizard steps to create a new partnership :
Step 1) Configure Partnership:
The partnership is fairly straightforward, we are using DemoUserDir for users, from our local client: www-demo-com to remote authz server: www-example.com.
Note: In our first example setup (not this one), we were passing SAMAccountName as a claim and using that as the lookup into the local user store - but this was really only a shortcut since we were using SSO AD user store - in fact the same physical AD on both our Client and Provider side.
So the following uses a more realistic example, where the unique entity passed from the provider is an email address and we then use the email address claim to do the lookup into our local user store. So the DemoUserDir, which is described latter does it's user lookup using the email address. And this partnership was called demo-to-example-via-email.
Step 2) User Configuration:
Here we select the "email" claim as the User ID Attribute, we are only passing through openid and email, and the userinfo URL comes from the Provider setup:
Step 3) SSO:
Again taking the Client setup and URL's,as entered in the prior document on setting up theCA SSO OpenID Connect Provider, we enter the SSO settings
Note: in the screen shot it uses persistent session - we did both and did samples where the claims were stored in the persistent session as well.
Step 4) Target Application:
We've identified the www.demo.com root directory as the target and are not using relay state here.
Step 5) Confirm:
Review and Confirm the settings.
Activate
After entry of the partnership we activate it, via "Action/Activate" button.
And in case you missed it - here is the "View" listing of the Partnership :
5) WebAgent for Access Gateway to service www.demo.com site.
As mentioned previously, in this case we used the same Agent Gateway server that was using for the OpenIDC Provider side. It is preferable to install to set them up separately and so I won't go into the details of how I did that, other than to note that we used the ACO AgentName mapping to allow us to give each site a different agent and independant protection policy: eg Agent Name Mapping:
Which allows us to give separate protection for agent "demoagent" for domain www.demo.com
In our Ag setup, the proxyrules.xml for www.demo.com are again simple, they just forward the request onto the localhost:81 where the default IIS 8.5 server is listening :
6) Change to www.example.com OpenIDC Provider to provide email claim.
For a more realistic federation we wanted our OpenIDC Client to use the email address as the lookup key into the user store. In order to do that we had to adjust our OpenIDC Provider to export the email address as a claim.
Note: This section referrers to changes that we need to make to the OpenIDC Provider side. All the other work in this document is setting up the "Client" SSO Policy Server/Agent Gateway side - where-as changes in this section apply to the "SSO OpenIDC Provider" setup - as described in the link earlier - also if you are setting this up correctly that may be a different policy server.
Determine what attribute in AD store contains email Address:
In finding an attribute that contained an email address, our test AD data does have a "mail" attribute but unfortunately it is not populated. So looking at the raw LDAP data, as screenshot below, we see that "userPrincipleName" does have the email address - so that is the field we will use to do the claim mapping.
Change Remote OpenIDC Provider to support claim "email"
On the Remote SSO Policy Server where we have defined our OpenIDC Provider we need to adjust the export claim for "email" from the userPrincipleName user attribute. This is done on the OpenIDC Provider setup, select Action/View & Modify :
Then in the Claims Mapping, section we change the "email" mapping :
And change it from the user "mail" attribute to the userPrincipleName attribute and save it.
Then we select "Save".
Change Remote OpenIDC Client to allow request for claim "email"
Still on the OpenID Connect Provider setup, we select the OpenID Connect/Clients setup - We select the www-demo-com client and "Action/View & Modify" button.
Note: just a reminder again - this section is on the "OpenIDC Provider" policy server - not the policy server where we are setting up the client side.
After selecting the www-demo-com client, we make sure the email scope is selected :
Then we select "Save".
Our provider is now setup with the claim "email" populated from "userPrincipleName" and our provider is aware that client www-demo-com can request this claim.
7) User Store setup for domain www.demo.com .
Back on the SSO Policy Server where we are setting up the OpenID Client Federation we want to setup a user store that is keyed from the federated attribute "email".
Since we are connecting to the same AD as used on the Provider side, and as described above, we know the email address is stored in the userPrincipleName field. So we setup this client side UserStore "DemoUserDir" with the LDAP User DN Lookup with via userPrincipleName as below:
This is the user store definition we will use on the OpenID Client side.
6) Policy to Protect the Client Demo Domain
On the client side www.demo.com we setup with agent demoagent some simple policy to protect the root site.
Policy:
Realm:
Realm with one Rule to AllowGetPost requests :
Note; we did both non-persistent and persistent - generally persistent is selected.
And a Policy that allows All users in DemoUseDir access to the "/" resource :
Users:
Allowed Rules:
Note: agentdemo since it is also on the Ag/SPS machine in our case also needs some special rules to take care of the /affwebvservices and /affwebvservices/public realms. If these are not set correctly the redirects via FWS will not work correctly, and may either prompt directly for credentials or not prompt at all.
The realms we need are :
And they can be applied fairly easily by adding "demoagent" to the FederationWebServicesAgentGroup" :
7) Access Gateway back channel call - trusting the https://www.example.com Website certificate.
The OpenIDC Provider site is accessed via https:// after making the initial redirect for authentication, the site www.demo.com makes a back channel call directly from Ag:www-demo-com -> www.example.com to collect the userinfo data. When it does that since it is an SSL call, the Ag:www-demo-com has to trust the X.509 Certificate provided by the www.example.com website.
Normally in Access Gateway adding a root CA is done via adding the cert to the SSL/certs/ca-bundle.cert file. But for FWS backchannel calls this is not the case - and the list of acceptable CA Certs is received from the policy server.
In our case the certificate for www.example.com is signed by the CA "Mark's Test CA" so we need to import this into the policy server. From the "Certificate Authorities List" we click the "Import Now" button and follow the wizard through the import process.
Signing wizard asks for file to import:
Displays some details of the CA Certificate :
And then asks you to confirm:
Now the backchannel calls that Ag:www-demo-com makes to www.example.com should now succeed.
If the Ag:www-demo-com does not trust the OpenIDC Provider website, then you will see this error message in the FWSTrace.log :
8) Trusting the OpenIDC Provider signing certificate.
The certificate you have setup in your OpenIDC Provider for signing the assertions, may also need it's CA Certificate imported before they will be accepted. In our case both the signing certificate from the Open IDC Provider and the Webserver certificate for www.example.com were provided by "Mark's Test CA" so we only had to import one CA certificate.
But your case may differ and you may need to import another CA root certificate chain.
9) Summary
That should be all you need to configure the client side of the SSO OAuth Partnership to SSO OpenIDC Provider.
I will also come back and review this article at latter stage, but thought it best to get out even in this more basic form.
Of course there will be problems, as we encountered when setting up as well. I've attached the backup.xml export of the policy store we have (all of the sensitive data has been removed, you can read it via Siteminder Policy Reader to get some idea of the policy, and I've included the fiddler trace of the successful access, and the dump.aspx pages we were using.
Further help obviously can be obtained from support case, or from posting in the communities.
Best of luck with your setup.
Cheers - Mark
----
Mark O'Donohue
Snr Principal Support Engineer - Global Customer Success