\nNote: This is by no mean <\/strong>required reading, you can successfully use Windows Azure AD\/ADFS\/etc without knowing any of the below, but I found that it helps to grok some of the basics. Up to you!<\/p>\n
Why Do We Validate Tokens?<\/h2>\n
Why do we bother validating tokens, indeed?<\/p>\n
When your Web application checks credentials directly, you verify that the username & password being presented corresponds to the ones you kept in your database.
\nWhen you use claims-based identity, you outsource that job (and the job of keeping track of your users\u2019 attributes) to an external authority\/identity provider. Your responsibility shifts from verifying raw credentials to verifying that your caller did indeed go through your identity provider of choice and successfully authenticated. The identity provider represents successful authentication operations by issuing a token, hence your job now becomes validating that token. More about what that entails in just a moment.<\/p>\n
Tokens and Protocols<\/h2>\n
Let\u2019s take a second to clarify an important point: tokens != protocols.<\/p>\n
Tokens are the form that issued credentials take to be transported, from authority to client and from client to resource. Some protocols have a preference for specific token formats: the SAML protocol only works with SAML tokens, OpenId Connect calls out JWT tokens specifically. Others can work with multiple tokens, provided that there\u2019s some kind of binding: WS-Federation usually works with SAML, but can work with JWTs and pretty much anything that gets wrapped in a binary token. OAuth2 doesn\u2019t mention any token format at all, given that it is mostly concerned with teaching to apps how to be clients (and clients should not care about the format of the tokens they handle, that\u2019s a matter between the authority and the resource).<\/p>\n Alrighty, what that that really mean to validate a token? It boils down to three things, really:<\/p>\n Let\u2019s examine all those in order.<\/p>\n If we would all be Econs<\/a>, using language with perfect property at all times, we would probably call this phase \u201cvalidation\u201d. However we usually lump in that term all checks, including the ones described later, hence I am forced to find a circumlocution like \u201cverifying that a token id well-formed\u201d.<\/p>\n When can you say that a token is well-formed? If the following holds:<\/p>\n A. The token is correctly formatted according to its intended format<\/p>\n B. The token has been received within its validity period, as validity is defined by the token\u2019s format<\/p>\n C. The token has not been tampered with<\/p>\n The meaning of A. is mostly that the token implements well the format specification it is meant to use. This is not as much as a security requirement, as it is a practical one: you\u2019ll have parsing logic meant to work with SAML1.0, SAML1.1, SAML2.0, JWT or whatever other format you support \u2013 and you don\u2019t want that logic to fail or to deal with ambiguous elements.<\/p>\n About B: it\u2019s a good idea for tokens to have a limited validity, as that gives the opportunity to re-assess the validity of the authority\u2019s assertions about the user often \u2013 without reasonably short validity periods, there would be no way of performing revocation. Verifying that a token has not been tampered with is more complicated to explain, but it\u2019s really not that complicated in itself. Those three tasks establish if a token \u201clooks good\u201d regardless of the context in which it has been issued and sent \u2013 if it is well formed. The next checks enter in the merit of the specific issuer and app being accessed.<\/p>\n You outsource authentication to a given authority because you trust it \u2013 but as you do so, it becomes critical to be able to verify that authentication did take place with your authority of choice and no else.<\/p>\n Tokens are designed to advertise their origin as clearly and unambiguously as possible. There are two main mechanisms used here, often used together.<\/p>\n In classic claims-based identity, every authority has both its own key and its own identifier. In scenarios including identity as a service, however, that might not be the case. For example: in Windows Azure Active Directory the token issuing infrastructure is shared across multiple tenants, each representing a distinct business entity. The signature of issued tokens will be performed with the Windows Azure AD key, common to all, hence the main differentiation between tenant will be reflected by the different issuer identifier found in the token. To be more concrete: a Contoso employee accessing a Contoso line of business app secured by Windows Azure AD will send a token signed by the same key used by a Fabrikam employee accessing a Fabrikam line of business app \u2013 but in the first case the token will have an Issuer value corresponding to the Contoso\u2019s tenant ID, whereas the latter will have the Fabrikam tenant ID. If the Contoso employee would attempt to access the Fabrikam app by sending his token, he\u2019d fail because the validation logic in from of Fabrikam\u2019s app would find in the incoming token the Contoso\u2019s tenant ID instead of the expected Fabrikam\u2019s tenant ID.<\/p>\n Both signature verification key and issuer ID value are often available as part of some advertising mechanism supported by the authority, such as metadata & discovery documents. In practice, that means that you often don\u2019t need to specify both values \u2013 as long as your validation software know how to get to the metadata of your authority, it will have access to the key and issuer ID values.<\/p>\n Tokens usually contain a claim meant to indicate the target app they have been issued for. As for the issuer, the identifier used to indicate the app is typically the representation of the app within the protocol used for obtaining the token.<\/p>\n That part of the token is often referred to as the audience<\/em> of the token. Its purpose is the same as the corresponding field in a bank check: ensuring that only the intended beneficiary can take advantage of it. An application receiving a token should always verify that its audience corresponds to the app\u2019s audience: any discrepancy should be considered an attack.<\/p>\n Imagine that Contoso is using two different applications, A and B, from two different SaaS providers. Say that one employee obtains a token for A and sends it over. A could take that token and use it to access B, pretending to be the employee: the authority is what B expects, the token has not been tampered with, it is still within its validity period\u2026 however, as soon as B verifies the audience, it will discover that the token was originally meant for A and not B itself \u2013 making the token invalid for accessing B and averting the token forwarding attack.<\/p>\n This check has an interesting property: whereas issuer value and signing keys are often discoverable from the authority via some specific mechanism (metatada documents, for example), the audience value must always be specified on a per-app basis. In other words, typically the only source of truth for what audience value should be considered valid for a particular resource is the resource itself \u2013 the developer includes that value as part of the resource configuration.<\/p>\n The checks described are the indispensible verifications one must perform to assess the validity of an incoming token. That is just the beginning, of course: knowing that the caller is actually Bob from Contoso does not mean that he has access to the resource he is requesting \u2013 rather, this gives you the information you need for performing your subsequent authorization checks if necessary for the business logic your app implements. A bit abstract, but hopefully not too <\/em>abstract Say that my resource is a Web API, protected by Windows Azure AD and specifically by the Contoso7 tenant. Say that we want to use JWT.<\/p>\n In order to be considered valid, an incoming JWTs will have to comply with the following:<\/p>\n \u2026and of course it will have to be still valid, not having been tampered with, and so on. Let\u2019s take a look at a token satisfying the above.<\/p>\n You can see highlighted in red the issuer value, in blue the audience, and in green the relevant claims used to assess whether the token is expired. See? It\u2019s really not magic!<\/p>\n That is not the token in its entirety, but only the \u201cbody\u201d. JWTs typically have<\/p>\n Each part is base64\u2019ed, hence you would not see the above in Fiddler.<\/p>\n Currently we offer various ways for you to inject validation logic in front of your application. You can choose to work directly with the JWT token handler<\/a> class, as shown here<\/a>, and configure it to use the above values as validation parameters. You can choose to use the OWIN middleware, as shown here<\/a>, which makes your job much easier but gives less control. You might even go completely manual and re-implement the JWT parsing & validating logic yourself, though that would be more work than you\u2019d likely want to do given that ready components are available. The key point is, ultimately all those techniques will perform the checks described above.<\/p>\n Well, I got to the end of the post and to my chagrin Sandra Bullock did not get an Oscar\u2026 and Her got far less recognition it would have deserved IMO.<\/p>\n On the other hand, now hopefully you have a deeper understanding of why we configure our validation middleware they way we do\u2026 hence I didn\u2019t completely waste the evening!
\nProtocols detail the ceremony that apps use to send users to authenticate to an authority and\/or clients use for sending tokens to apps for gaining authenticated access. In other words, protocols are used for moving <\/em>tokens.<\/p>\nMechanics of Token Validation<\/h2>\n
\n
Well-formed<\/h3>\n
\nEvery token format defines some mechanism for expressing validity intervals: SAML has NotBefore and NotAfter clauses, JWT has ExpiresIn, and similar. Verifying those is just a matter of parsing the values and comparing those with the local time of the authority, modulo any clock skew if known.<\/p>\n
\nAll the token formats I listed establish that a token must be digitally signed <\/em>by the authority that issues it. A digital signature is an operation which combines the data you want to protect and another will known piece of data, called a key<\/em>. That combination generates a third piece of data, called the signature. The signature is typically sent with the token, accompanied by information about how the signing operation took place (which key was used, what specific algorithm was used).
\nAn application receiving the token can perform the same operation, provided that it has access to the proper key<\/em>: it can then compare the result with the signature it received \u2013 and if it comes out different, that means that something changed the token after issuance, invalidating it.
\nGiven their importance I must make one special mention for one special class of keys, X509 certificates. Without getting in the details, let\u2019s say that certificates rely on a technology (public key cypto) that used 2 different keys, one for signing (which remains private: only the authority has it) and once for verifying the signature (which is public, known by everyone and distributed via certificates). In order to verify a signature places by a private key, an app receiving the token needs to have access to the certificate containing the corresponding public key.<\/p>\nComing from the Intended Authority<\/h3>\n
\n
Intended for the Current Application<\/h3>\n
Other Checks<\/h3>\n
\nSpecific resources and app types might consider some subsequent checks so important that they should really be part of the token validation proper \u2013 examples include the value in the scope claim for OAuth2 bearer flows. Many middlewares offer extensibility points you can use for injecting your own validation logic in the pipeline; but it is also common to add the extra checks directly in the app, in constructs typical of the stack used (e.g. filters & attributes in MVC) or even in the first few lines of a method call.
\nIn the end all it matters is that the logic is executed before access is granted, which in practice usually means before the interesting app code gets to execute. As long as you are satisfied that this happens, you can choose to draw the logical line that groups the \u201ctoken validation logic\u201d wherever you deem it most appropriate.<\/p>\nAn Example<\/h2>\n
![\"Smile\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/03\/wlEmoticon-smile.png\")
\nHere, let\u2019s illustrate the concepts with one example.<\/p>\n\n
\nThe first 2 values came straight from the Contoso7 metadata document. The audience corresponds to the ID I have chosen to assign to my API when I provisioned it in my directory.<\/p>\n![\"image\"](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/03\/image_thumb.png\" "\\"image\\"")
<\/a><\/p>\n\n
Wrapup<\/h2>\n
![\"Winking](\"https:\/\/www.cloudidentity.com\/blog\/wp-content\/uploads\/2014\/03\/wlEmoticon-winkingsmile.png\")
<\/p>\n