Skip navigation
All People > Sascha Preibisch > Sascha Preibisch's Blog

New Release

We are happy to announce that OAuth Toolkit 3.5.00 (OTK-3.5.00) has been released today (Friday, 8. July 2016)!


What is new?

After a long time of customers asking for it we have updated the authorization endpoint (/auth/oauth/v2/authorize).

These are the main updates:

  • by default the login and consent screen are now on different views. Users will first be presented with a login page, followed by a consent page
  • the API supports the parameters id_token_hint, acr_values, prompt in the context of OpenID Connect
  • the API creates a JSON Web Token (JWT) with some session values. Having that enables customers to externalize the login process just as the consent process to different servers. (Please note that the session JWT is not replacing the default session handling. It is an addition to it)
  • the API has been divided into 3 API's all together. login and consent are handled in their own API

We are hoping that this new version enables our customers to do less of customization within this API. It should enable customers also to implement requested features/flows such as 'I would like to design the consent screen based on an authenticated user/ user group' or 'I would like to limit SCOPE by users/ user groups'.


What has changed otherwise?

A few smaller changes have been implemented:

  • The same API (/auth/oauth/v2/authorize) used to display a checkbox on the login screen to keep users logged in if they wanted to do so. That checkbox has been removed. In order to keep that behaviour clients now have to use the parameters 'id_token_hint' and 'prompt'
  • In order to enable the session JWT two additional values have to be configured. One for signing and one for encrypting the JWT. Configuring these two values is required for the out-of-the-box OTK installation!
  • For the complete documentation please refer to CA Technologies Documentation  and search for OAuth Toolkit


What's next in this blog?

In the next few days we will publish a guideline on how to leverage an external 'login-server'.



As always, let us know how you like the new version, what is good, bad or missing!


I am happy to share with you a few videos that we have created in the context of OAuth Toolkit and Mobile API Gateway. They are meant as an introduction into how API's can be built and what kind of elements are available to secure those.

We decided to create these videos because we have been asked for guidelines on typical tasks that are involved when designing and implementing API's. They are not meant to replace a workshop but to give a brief overview.



Please let us know if those videos are considered to be helpful, what may be missing, what is good or bad  and if there are other topics that should be covered by videos.


One note

My voice is pretty slow so please have a cup of coffee to make sure you do not fall asleep!


More important

We only talk about authentication not authorization.  We did not meant to call OAuth an authentication framework, it is just that authentication was what we needed in this tutorial. This clarification is required to make sure that we do not get haunted by those two guys (Nat Sakimura, John Bradley, OpenID Connect | OpenID ):





Please follow the links below to find the videos:

Part 1 - MAG Building protected APIs Part 1 - YouTube

Part 2 - MAG Building protected APIs Part 2 - YouTube

Part 3 - MAG Building protected APIs Part 3 - YouTube

Part 4 - MAG Building protected APIs Part 4 - YouTube

Part 5 - MAG Building protected APIs Part 5 - YouTube

Part 6 - MAG Building protected APIs Part 6 - YouTube

Part 7 - MAG Building protected APIs Part 7 - YouTube


Thanks for your feedback!

Dear car vendors,


As it happens I am reading more often about cars that can be controlled by API’s. First I thought that’s cool. And actually, it is cool! Being able to build, or at least, use an app that enables me to select a welcome song that my car plays when I open the door or that unlocks the doors because I am getting close to the car sounds like a lot of fun.


Unfortunately I am reading even more often that these API’s are not secure! That almost anybody, not only myself, can control my car via those API’s. That those API's even return required credentials if they were missing in a request.


That is not acceptable!


I am not sure if you, car vendors, use that technology yourself in your private life. Or if you are too afraid to do so. I am! And that is why I like my very basic Hyundai Elantra so much: no API’s == secure! (what a depressing statement! But it seems to be correct for many connected cars).


The latest news I read was about Nissan LEAF:


As a software architect, who is building secure API’s on top of reliable products (Features | CA Mobile App Services ), it is difficult to understand why this happens again and again. Why are API’s in cars often insecure? Why is there no awareness that insecure API’s are bad?


These are my theories:

  • car vendors are no software engineers and therefore they do not understand the technology
  • car vendors believe that keeping an API definition secret makes it secure
  • car vendors are too proud to ask experts on API design for help
  • car vendors believe that only their app can send a request to the car’s API
  • car vendors categorize API's as cost center but not as profit center and therefore invest as little as possible
  • car vendors try to be early adopters of technologies although they do not know what they are doing


This is what I think you should do, dear car vendors:

  • hire experienced software engineers
  • add a piece of hardware to your cars, a HSM (
  • add a policy based API gateway to your cars. Even if it is just ‘simple’
  • do not mix API’s for reading data and controlling the car


Once you have all of that in place use well known technologies such as OAuth, OpenID Connect, JSON Web Token and PKI to build API’s.


You will suddenly have API’s that are secure, well documented, you can provide open source SDK’s and build a developers community around them. You will be cool and hip!


And the best of it all:


No news about insecure API’s! Because there are none!

The Mobile API Gateway in conjunction with the mobile SDK enables developers to build secure apps with minimum effort. App developers can start implementing the app without worrying about security. That is taken care off by the SDK's.

We are very proud to announce that our mobile SDK is now open source!

It can be found on github: CA API Management · GitHub

The SDK's are available for iOS and Android (not yet open source) and support features like this:

  • Certificate based device registration
  • SSL/ SSL with client authentication
  • OAuth
  • OpenID Connect
  • Social Login
  • SSO between apps on different devices
  • A framework called "Enterprise Browser" which shares an SSO session with third-party-apps

Check it out and let us know how you like it!

I often get the question on how to create token lifetimes per client. OTK by default issues token with a global lifetime which becomes a limitation in many cases. This blog post is about customizing token lifetimes per client.


Since OTK-3.3.01 (January 2016) client_id's can be configured with a JSON structured custom field. The content of that field is available in policy for certain tasks during OAuth request processing. Here are the required steps from "Register a new client" to "issue token with custom token lifetime":


The process is divided into 2 parts and will take about 15 minutes to implement:

  1. Register a test client in OAuth Manager
  2. Modify one policy


It starts with OAuth Manager (https://your-gateway:port/oauth/manager):

  1. Select "Clients -> Register A New Client"
  2. Use the name "AAA Test Client", the Organization "AAA Test" and click "Register"
  3. Select "Clients" and look for "AAA Test Client"
  4. Select "List Keys -> Edit". At the bottom of the screen you will find a custom field containing "{}" (an empty JSON structure)
  5. Paste this content into the custom field:  {"lifetimes": {"oauth2_access_token_lifetime_sec": 86400, "oauth2_refresh_token_lifetime_sec": 432000}}
  6. Click "Save"


This client_id now has a custom field which we will use to generate access_token with a lifetime of 86400s (1 day) and refresh_token with a lifetime of 432000s (5 days).


The next step is to modify the policy that generates token: OTK Generate OAuth Token. This will be done in the Policy Manager:

  1. Login to Policy Manager using admin credentials
  2. In the lower left window search for "OTK Generate OAuth Token" and open the policy in the editor window; turn on "Show Comments" and "Show Assertion Numbers"
  3. On line 5 you will find "OTK Token Lifetime Configuration". That assertion generates global lifetimes which we will overwrite
  4. All together, including container assertions (At least one ..., All assertions ...) we have to add 9 lines of policy


To give you an idea, the result of this customization will look like shown below. I hope you can see that it is easy to do:


Ok, let's get started:

  1. line 6: add the assertion "At least one ..."
  2. line 7: add the assertion "All assertions ..." as the fist child of the "At least one ..." assertion
  3. line 8: add the assertion "Continue Processing" as the second child


You should have this picture now (without the comments in the screenshot unless you also added those):


All the next assertions will be added into the block on line 7. I will explain each line with all necessary details:

  1. line 8: add the assertion "Set Context Variable". Configure it as follows:
    1. Variable Name: custom_json
    2. Data Type: Message
    3. Content-Type: application/json; charset=UTF-8
    4. Expression: ${custom}. The variable ${custom} contains what was specified in the custom field in OAuth Manager
  2. line 9: add the assertion "Compare Expression" to check if the content includes the value "lifetimes" which indicates that custom lifetimes were configured
    1. Variable: ${custom_json.mainpart}
    2. Add ... Simple Comparison ...
    3. Select "contain" in the second drop-down list, select "does" in the first drop-down list
    4. Right Expression: lifetimes
    5. Uncheck "Case Sensitive", click "OK"
    6. Click "OK" to close the assertions dialog
  3. line 10, 11: add the assertion "Evaluate JSON Path Expression". Both are similar, one is extracting the "access_token" lifetime, the other the "refresh_token" lifetime:
    1. for the access_token lifetime:
      1. Expression: $..lifetimes.oauth2_access_token_lifetime_sec
      2. Other Message Variable: custom_json
      3. Variable Prefix: at_lifetime
    2. for the refresh_token lifetime:
      1. Expression: $..lifetimes.oauth2_refresh_token_lifetime_sec
      2. Other Message Variable: custom_json
      3. Variable Prefix: rt_lifetime
  4. line 11, 12: add the assertion "Set Context Variable" to overwrite the global lifetime variables oauth2_access_token_lifetime_sec and oauth2_refresh_token_lifetime_sec
    1. for the access_token lifetime:
      1. Variable Name: oauth2_access_token_lifetime_sec
      2. Data Type: String
      3. Expression: ${at_lifetime.result}
    2. for the refresh_token lifetime:
      1. Variable Name: oauth2_refresh_token_lifetime_sec
      2. Data Type: String
      3. Expression: ${rt_lifetime.result}


Click "Save and Activate", create a revision history comment "Customized Token Lifetime".


That's it!


You can now use a tool like Chrome's Advanced Rest Client and use the "password" grant_type with your new client_id and client_secret. The response will have the configured access_token lifetime of 86400 s in the response:



"access_token": "065d8941.....ae29b9e1e1"

"token_type": "Bearer"

"expires_in": 86400

"refresh_token": "f03f133f.....42841e0722"

"scope": "oob"



Any feedback is welcome, especially if it helps you!

Last week we have released a new OAuth Toolkit, version 3.3.01. The version mainly contains bug fixes but also a nice new feature:

  • a custom field for client_id's
  • a custom field for issued access_token


Why is this a nice feature? Because those fields enable users of OTK to implement more validations on OAuth protected APIs and customized behaviour for certain client's.


I will write a few blog posts about ideas on how to use those fields.

Sascha Preibisch

Latest news in OAuth

Posted by Sascha Preibisch Employee Jan 13, 2016

I have been quiet for a while. But recently new OAuth related RFC drafts came up. I just want to share that info with anyone interested.


Please follow these links to see the latest works that are related to threats referred to as “IdP Mix-Up” and “Malicious Endpoint”:

- Mike Jones: self-issued » OAuth 2.0 Mix-Up Mitigation


Next week CA World 2015 will start.


I will be there working at the SmartBar ('Meet the Expert' in last years terms) to answer any OAuth, OpenID Connect, CA API Gateway or CA Mobile API Gateway related questions. In addition, Ola Mogstad and myself will have a tech talk on Thursday showing how the CA API Gateway/ CA Mobile API Gateway can be used for very different API related tasks.


This will include oauth, social login, leveraging CA Advanced Authentication for additional security and other technologies.


See you next week!

A microservice should be an easy to maintain and feature oriented API. Nevertheless it needs to be secured. That may be just as difficult as with any other API. Luckily, if OAuth is used, there are many possibilities for securing the service and implementing many kinds of validations by simply requiring an access_token as a credential.


If you look at the graphic below you will see how many attributes are associated with a single token (or might be associated, depending on your OAuth product features):


Screen Shot 2015-10-21 at 11.44.34 AM.png

Knowing that enables an API developer to verify a few or maybe even all of those attributes to secure access to the service. Here are some ideas of what could be implemented based on this knowledge:

  • access control based on username (resource_owner)
  • access control based on client_id
  • access control based on access_token age and maybe the last usage. A sliding window as with cookies can be implemented
  • limited feature set based on the used grant_type. For token that were issued based on an implicit grant_type the API may be more restrictive than for token being issued via an authorization_code grant_type
  • access control by granted SCOPE, the most obvious choice in the context of OAuth
  • denying access for public clients


The next time you hear someone saying: OAuth does not fit into the microservices world, explain the benefits!

Lately I got involved in discussions that had “OAuth and Step-Up Authentication” as its topic. The question always was about how to tie OAuth access_token and other credentials together.


The idea of Step-Up Authentication is that an API can only be consumed if a credential with a higher (or different) assurance level is available. For example, a transaction API may require an access_token for general use. In addition, because that access_token is used with parameters that indicate a high risk transaction, the API wants to assure that the current resource_owner is still the one associated with the access_token. For that, it requires an OTP as an additional input parameter.

After considerable debate we discovered that it comes down to this:

  • Step-Up Authentication is a hierarchical order of credentials. It may be a list of individual credentials or credentials derived from each other


Looking at it that way may simplify things. Instead of finding of a way on how to tie credentials together it may be sufficient to simply require multiple ones of different types.

Imagine something like this:

  • the transaction API will handle two cases: lower assurance level required, higher assurance level required. This decision on what is required can be based on incoming parameter values or in conjunction with systems like CA Advanced Auth
  • the transaction API will process credentials in an hierarchical order, from low to high
  • it first requires and validates an access_token. This is the minimum requirement to get access to this API and reflects the lower assurance level in this scenario
  • for the higher assurance level the API requires an additional OTP

This is a simplified view but it shows the logic that could be used.

In order to make this work, it is certainly required that the API is well documented. Documentation also needs to explain how to retrieve a valid access_token and/ or an OTP and in which case they have to be provided.

Sascha Preibisch


Posted by Sascha Preibisch Employee Sep 15, 2015

I get many questions on how SCOPE works and on how it is handled in OTK. I will try to answer that question right here and now.


General rules:

  • OAuth clients have to be registered using OAuth Manager
  • OAuth clients can be registered with a space separated list of SCOPE values. These case sensitive values can be specified as desired. The target API has to be configured to exactly match those values
  • OTK will receive OAuth token requests and will only issue SCOPE values that were registered for the requesting OAuth client
  • OTK will not do any SCOPE verifications on OAuth protected APIs UNLESS the API author wants it to do so


Here is an example:

  • a developer registers a new OAuth client using OAuth Manager. The registrations includes valid SCOPE values 'READ WRITE'
  • a developer implements an API on the CA API Gateway or CA Mobile API Gateway. For its protection the API requires SSL and a valid access_token
  • since this API will be able to accept READ access, WRITE access and both it implements several flows:
    • if the access_token was granted for SCOPE=READ the API will only accept READ requests
    • if the access_token was granted for SCOPE=WRITE the API will only accept WRITE requests
    • if the access_token was granted for both, the API will accept both requests




As of here I will answer questions that I have received for the topic SCOPE. I will try to answer them with examples.


Q 1: Sascha, in earlier releases (before OTK-3.0.0) OTK did not check SCOPE by default, I had to implement checks myself. How does it work today (as of OTK-3.0+ shipped on gateway 8.3+)?


A 1: OTK only accepts requested SCOPE values that were registered for a given client. The assertion 'OTK Require OAuth 2.0 Token' that is used to protect APIs now takes desired SCOPE values and validates a given access_token against those. If not all required SCOPE values were granted to that access_token, the request will fail.

Example 1:

Issuing token: A requesting client, let's say a client that uses the authorization_code flow, sends a code request that includes the URL encoded parameter '...&scope=READ%20DELETE&...'. OTK will automatically check if the SCOPEs 'READ' and 'DELETE' have been registered for the specific client. If that is the case it will grant the SCOPE, if not, it will remove all non-registered SCOPE values. In this case 'READ' would have been granted where as 'DELETE' would have been removed from the list. If the client had included 'DELETE' only the request would have failed.

API protection, requiring token: The API developer would include the assertion 'OTK Require OAuth 2.0 Token' in its API. That assertion will require 'READ' since the API developer has made the decision that at least 'READ' must have been included. The assertion will only accept the request if the access_token has not expired, is not disabled and has been granted for 'READ'. Following that assertion the API developer will implement branches. Depending on the granted SCOPE the API will accept a READ request or a WRITE request or both. To do that the assertion 'OTK SCOPE Verification' can be used. One branch would be executed if both SCOPEs were granted, 'READ" and 'WRITE', other branches for the case that only one of them has been granted.


Q 2: Sascha, the /token endpoint, how and where does it validate SCOPE?

A 2: The token issuing endpoint /auth/oauth/v2/token verifies SCOPE for all token requests very early in the policy. Find it by searching for the assertion 'OTK SCOPE Issuing'.  There is just one exception: grant_type=authorization_code. SCOPE for that grant type is verified when the client sends the initial response_type=code request. In addition some grant_types require special handling. Find those within the folder 'OTK-<version>/Policy Fragments/grant_types/*'.

Example 2: Use the CA API Policy Manager to explore the API of /auth/oauth/v2/token

Sascha Preibisch

My first blog

Posted by Sascha Preibisch Employee Sep 15, 2015

Hi there!


My first blog, just to get started.


Let's put some real content in here now.