Layer 7 API Management

Expand all | Collapse all

Layer7 API Gateway OAuth - using CA Siteminder/SSO as external login

Jump to Best Answer
  • 1.  Layer7 API Gateway OAuth - using CA Siteminder/SSO as external login

    Posted 07-25-2019 07:04 PM

    How to setup Siteminder/SSO as the custom login server in the APIM Gateway OAuth toolkit.

    I am fairly pressed for time, but wanted to provide outline of how we achieved this - so this will be in some areas a bit brief but hopefully it paves some of the gaps and helps anyone else who wants to do this to make their own way.  Sample policy is attached.

    1. Why: 

    • The current API Management OAuth Toolkit does have some integration steps for us with Single Sign On,

      But this is a backend integration with SSO, where the toolkit presents it's own UN/PW login page and then the gateway makes a call to Siteminder/Single Sign On to authenticate.

    • A more natural way for most browser based SSO protected applications are to redirect to a login process (usually a login.fcc page) and to return with an SMSESSION cookie, which is the consumed for authorization purposes.

    • Sending the credentials in with the login request, and receiving a 401 if failed - as per the Toolkit default SSO integration - is going to be a more natural authentication method for pure API calls.  However for browser based uses, with SSO they will get a 302 redirect to a login process - often if you are a raw API call you don't want to handle a 302 redirect.  So this process is really for applications that are using browser based access.

    • There are steps in the API Gateway documentation that show how to process an SMSESSION cookie for authorization, but these are not able to be directly applied to the OAuth toolkit (most of the Toolkit services and encapsulated assertions cannot be modified and are read-only)

    • Often Single SIgn On customers have their own customized authentication login pages (based around the Siteminder login.fcc page processing) 
    • API Mobile Application Gateway has some special encapsulated assertions for Single Sign On support
      But these are not accessible or usable in the vanilla API Gateways + OTK setup. 

    2. Relevant documentation : 

    CA API Gateway - 9.4

    CA API Management OAuth Toolkit - 4.3

    3. Custom login server in the APIM Gateway OAuth toolkit

    It includes the following link to Sasha's blog that has been removed with the transfer to new communities platform;
    I've added a note to the documentation so that should be fixed/restored somewhere down the track. 

    4. Login Page in OAuth ToolKit : 
    Essentially, there is a login flow that happens when you POST to :
    That then redirects you to the 

    Which gives the login page :

    Whereas if we want to use a Siteminder/Single Sign On Login page, it would be on a different server, and look something like this : 

    5. Changing the login flow : 

    As per the Toolkit documentation we set an external login process.  In this case we are going to create /authorize/smlogin, as a modification of the /authorize/login process.  So we modify the policy :  '#OTK Authorization Server Configuration" to point to our smlogin page.

    We then copy the login policy and save it as smlogin : 

    A good tip for viewing the policy is the have the "Show Comments" and "Show Assertion Numbers" checked - particularly for the OTK, as it has quite a number of comments & labels. 

    Under the tasks section, normally there is "display" and then "login" tasks, which display the login page to the user, and then process the login POST request.

    6. Modifying the Display Task 

    In our case we want to modify the "display" process to do a 302 redirect to our "Single Sign On" login.fcc page.  And we want that call to specify a TARGET parameter (SSO speak) that will redirect back to this page, with the action=login, after the user has logged into SSO and has an SMSESSION cookie.

    Here is the modified "display" task : 
    Notes : 
    • You can see at line : 298, the original returned page which is the default login page.

    • In this task instead we check the protected resource (line 281), which then sets in ${siteminder.smcontext.realmdef.formLocation} where the login.fcc page is located.

    • The lines, 283 - 290 build the TARGET/ ${smtarget} variable in comparable format for Single Sign On for the login.fcc page.  SSO uses TARGET parameter to workout where to return to after authentication.

    • The line 292, sets the other parameters needed for SSO,  REALMOID is hardcoded, but can also be got from a reamdef attribite,

    • The tricky parameter in line 292 is SMAGENTNAME. It's encoded by SSO, so you will need to get that from an existing agent,  there may be a way to encode it - but I'm not aware of it.  But these hardcoded SMAGENTNAME values are not unusual in custom SSO pages.

    • The URLencode at 287 plus the bit of javascript is to encode in smencode format, its a rough way to do it but it works - a better way would be to implement a javascript method do to the whole smencode process (there is a java sample). 


    7. Modifying the Login Task 

    The login task didn't need any modification in the smlogin process.
    The one I've uploaded does have replacement "XOTK User Authentication" - but that was just to assist me in debugging so I could add debug lines.

    We do however need to modify "OTK User Authentication Extension"  :

    Here we need to comment out lines 7 and 8 (since we are validating via SMSESSION cookie, so will not have username and password).
    Then lines 23 - 38 are as documented in the API Gateway manual for SSO integration for SMSESSION.
    Most of these were here already, but we changed 27 : "Authenticate against CA Single Sign On" to accept a cookie as well. 

    The modified "Authenticate against CA Single Sign On" at line 27: 

    8. Running login test case via OAuth Test Client

    Using the "Basic Client Profile" in "OAuth V2 Clients"  here is the network trace of the /authorize process :

    We can see bcp click then does a GET for /authorise, which redirects to /smlogin, which then redirects to login.fcc.
    After we enter UN/PW on the login.fcc page, and do a POST back to login.fcc,  Single Sign On authenticates the user sets an SMSESSION cookie, and redirects back to the /smlogin process on the API Gateway, which now passes the smlogin?action=login.   We then drift through the consent page and then back to the bcp page with the authorization_code.    The bcp page the makes backchannel calls to get the details of the tokens and claims.

    8. Adding a pre-display task (display-login)

    One extra condition is - what if we already have a SSO SMSESSION cookie.  In that case rather than doing the action=display task, we can skip and directly do the action=login task.   However if we fail (perhap the SMSESSION is expired for example) then we would then want to default to doing the action=display, so that we process the login via the login.fcc page as normal.

    There are a few ways to solve it, here we created a display-login task, that is essentially a copy of the login task, but checks that the action=display at line 44. And where rather than error condition at 194, we allow the display-login branch to fail if the Authentication fails.  So if the pre-display task fails, then it will try processing the 2nd in the "At least one of" list, and we will then process the action=display as normal.

    This way we try to login, and if the user already has an existing valid SMSESSION cookie, then we skip the login page entirely and go directly onto the consent page.

    9. Other Steps 

    Clearly there are some more setup steps required.  Such as setting up the resource as protected in the Single SIgn On world, and registering
    the API Gateway as SSO agent with the SSO policy server.

    Also in the xml samples uploaded it is coded to skip the consent screen.  It still goes through the consent page, but does so with a "grant" setting directly rather than the "prompt" setting which prompts the user - that was just a requirement for this particular example.

    Hope that helps with your setup.

    Cheers - Mark


  • 2.  RE: Layer7 API Gateway OAuth - using CA Siteminder/SSO as external login
    Best Answer

    Posted 08-05-2019 09:27 AM
    It would also be possible to combine both the pre-display and the login steps into one step - since they are largely identical.

    It just require the combined request is prior to the "display", that it checks for login or display steps, and then  - if process of SMSESSION fails - that it only raises an error if the state was "login" and not "display".

    I left it as I did since the explanation was simpler - but one branch would save some duplication of code.

    Cheers - Mark