What is an opaque token? - oauth

And what does it mean that they are in a "proprietary format"? I am reading about JWT refresh tokens and they are opaque tokens, but I don't understand the term.

A JWT has readable content, as you can see for example on https://jwt.io/.
Everyone can decode the token and read the information in it. The format is documented in RFC 7519.
An opaque token on the other hand has a format that is not intended to be read by you. Only the issuer knows the format.
The meaning of the word already gives a hint:
opaque
/ə(ʊ)ˈpeɪk/
adjective
not able to be seen through; not transparent.
Here's a quote from https://auth0.com/docs/tokens:
Opaque tokens: Tokens in a proprietary format that typically contain some identifier to information in a server’s persistent storage. To validate an opaque token, the recipient of the token needs to call the server that issued the token.
A "opaque JWT refresh token" is a contradiction as per definition above. What actually is meant here is, that in some JWT frameworks only the authentication token is a JWT, but as refresh token they use opaque tokens.

Here, the term "opaque" means the string (that serves as token) is like a reference (in OOPs), or pointer (in C), or foreign keys (in relational DBs).
i.e. You need an external content to resolve it.
Simple versus Composite:
The string is a "simple" string, as opposed to JWS, where is "composite"; It has parts "inside" it.
Inside versus Outside:
You can extract a payload (with claims, etc) out of it without referring to an external server or storage, "outside" this string.
Since an opaque token is a simple string it is just a reference, hence, naturally, its format is entirely arbitrarily determined by the server that issues it (hence the term "proprietary format"). The token string is determined at the time of creation of the underlying (referred-to) content, i.e. when it is paired (associated) with the contents that this token (as the reference or foreign key) refers to.

Related

Is it possible to get profile information in an id_token from Google?

When using Google's OpenIDConnect authentication system, it's possible to specify email or profile or both in the scope parameter. If you request the email scope, the "email" and "email_verified" claims will be included in the id_token that gets returned as part of a successful OAuth2 authentication session.
Here's an example from Google's documentation:
An ID token's payload
An ID token is a JSON object containing a set of name/value pairs.
Here’s an example, formatted for readability:
{"iss":"accounts.google.com",
"at_hash":"HK6E_P6Dh8Y93mRNtsDB1Q",
"email_verified":"true",
"sub":"10769150350006150715113082367",
"azp":"1234987819200.apps.googleusercontent.com",
"email":"jsmith#example.com",
"aud":"1234987819200.apps.googleusercontent.com",
"iat":1353601026,
"exp":1353604926,
"hd":"example.com"
}
However, requesting the profile scope seems to have no effect whatsoever on the contents of the id_token. In order to retrieve the profile information, you have to make a separate HTTP request to a distinct endpoint (authenticated with the access_token you just received) to get a document that looks very similar, but with more information:
{
"kind": "plus#personOpenIdConnect",
"gender": string,
"sub": string,
"name": string,
"given_name": string,
"family_name": string,
"profile": string,
"picture": string,
"email": string,
"email_verified": "true",
"locale": string,
"hd": string
}
Ideally, I would prefer to get the profile information (just name, actually) included in the id_token JWT rather than having to make a separate call. Is there any way to specify additional fields and have them included as claims in the id_token? If not, why is email treated specially and returned in the id_token?
Starting today you will get profile information when exchanging the code at the token endpoint (i.e. using the "code flow").
How to use: add the profile scope to your request, and make sure you are using the OpenID Connect compliant endpoints (the ones listed in https://accounts.google.com/.well-known/openid-configuration).
Look for claims such as name and picture in these ID Token responses. As before, if the email scope is in your request, the ID Token will contain email related claims.
When you refresh your access token, every so often the ID Token that is returned with the fresh access token will also contain these additional claims. You can check these fields, and if present (and different to what you have stored), update your user's profile. This can be useful to detect name or email address changes.
When a request is made with response_type=id_token and profile in the scope like scope=openid+profile+email, the resulting id token should contain the profile claims directly in it.
This is per section 5.4 of the OpenID Connect spec, which says "... when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token."
However, in a little testing I did with their OAuth 2 Playground, Google doesn't seem to put profile claims in the id token even when response_type=id_token and no access token is issued. I'd argue that this is an implementation defect on Google's part and, short of them fixing that (or adding support for the "claims" Request Parameter), there doesn't seem to be a way to accomplish what you're looking for.
Well, this is the right place to request. We are working to support this feature and should be rolling this out soon (in the next few weeks). I'll make an update to this response then.

Node JWT library njwt verifies a token even though it differs from original

Trying out Stormpath's njwt package for handling JWTs as per this answer by #robertjd.
While trying to see what the various error messages are when verify()ing a token, changed a single character (the last one) of a token expecting the verification to fail, but to my surprise it passed and showed the contents of the token correctly.
More precisely, I changed the last character from an A to a B. This seems to not be the general case, since making other single character changes leads to the expected JwsParseError with message Signature verification failed. I tried this with both the default HS256 and with HS512.
Is that behavior legitimate for JWTs i.e. that the last char is redundant and doesn't affect the verification checksum? Or is it an issue in the njwt library?
Sub-question to njwt's maintainers: in getting back the token after verification, the header's algo property always has a value of none. I see in your source code that you explicitly set it so. Why is that?
Update: regarding the sub-question for the "algo": "none" in njwt's callback of verify(), it seems that "none" signifies that the digital signature is not included, which is the case when we get the token in the callback. Correct me if I'm wrong.
This is due to the base64 (technically, base64url) encoding, which is defined in RFC 4648. The low-order bits of the final (non-padding) character in the encoded data might not be used, so changing from A to B might not have a material effect on the decoded value.
Try changing any character but the last :)

Oauth 2 - params ordering and signature integrity

I have two questions:
Q1: Why does OAuth2 require params to be ordered and encoded (for 2-legged)?
All it has to worry about is the matching signature in both the end for the given data(query string).
We can just check the signature generated using the query string.(e.g ?a=1&b=2). Since the signature is generated based on the secret key which is known only to the client and provider, we can only consider the query string without any ordering/encoding.
So, what's the advantage in doing ordering/encoding and then creating the signature?
Q2: How can this signature save me from man-in-the middle attack?
If I have to make a request like this to my server from a client:
increaseUserPoints?userId=1&pointsToAdd=5&appId=x&token=XYZ
Now the token XYZ will be always same, so a hacker could keep posting the same request to increase points. Since the generated token from the given appId is the same, the server will allow this. How is this case handled?
Q1: Ordering the query parameters brings sanity to the HMAC.
Let's say you have two parameters: 'pointsToAdd' and 'appId'. Using the query string pointsToAdd=X&appID=y creates a different HMAC to appID=y&pointsToAdd=X. Because both you and the server need to generate the same HMAC to verify the requests having unordered query parmeters plain fails.
Q2: This saves you from an attack because only you and the server know how to sign your request.
You have a secret key, and only you and the server knows it. This key signs the request. If the HMAC doesn't match according to this secret key, the request fails.
Because all parameters have been used to create the HMAC the request is secure from MITM attacks — a hacker can't change, add or delete any query parameters, or the server will produce a different HMAC when it attempts to authorise and the request fails.

Antlr3 - HIDDEN token in the parser

Can you use a token defined in the lexer in a hidden channel in a single rule of the parser as if it were a normal token?
The generated code is Java...
thanks
When you construct a CommonTokenStream, you tell it what channel to use. Tokens on other channels will not be visible to the parser.
Yes you can use a hidden token in the Parser.
We do this all the time. The only problem is that you need to know when to look for it.
Antlr has a few pieces of terminology that it uses.
A Hidden token just travels on a separate stream. The user can always check for hidden tokens by calling getHiddenAfter or getHiddenBefore on a currently matched token.
Note: There may be more than one token hidden, before or after, a matched token so you should iterate through them.
A Discarded token is actually removed when you tell the lexer to discard it. It will never be seen by you again.

What are the characteristics of an OAuth token?

How many characters long can an oauth access token and oauth access secret be and what are the allowed characters? I need to store them in a database.
I am not sure there are any explicit limits. The spec doesn't have any.
That said, OAuth tokens are often passed as url parameters and so have some of the same limitations. ie need to be properly encoded, etc.
OAuth doesn't specify the format or content of a token. We simply use encrypted name-value pairs as token. You can use any characters in token but it's much easier to handle if the token is URL-safe. We achieve this by encoding the ciphertext with an URL-safe Base64.
As most people already pointed out. The OAuth specification doesn't give you exact directions but they do say...
cited from: https://datatracker.ietf.org/doc/html/draft-hammer-oauth-10#section-4.9
"Servers should be careful to assign
shared-secrets which are long enough,
and random enough, to resist such
attacks for at least the length of
time that the shared-secrets are
valid."
"Of course, servers are urged to err
on the side of caution, and use the
longest secrets reasonable."
on the other hand, you should consider the maximum URL length of browsers:
see: http://www.boutell.com/newfaq/misc/urllength.html
If you read the spec, it says,
The authorization server issues the registered client a client
identifier - a unique string representing the registration
information provided by the client. The client identifier is not a
secret; it is exposed to the resource owner, and MUST NOT be used
alone for client authentication. The client identifier is unique to
the authorization server.
The client identifier string size is left undefined by this
specification. The client should avoid making assumptions about the
identifier size. The authorization server SHOULD document the size
of any identifier it issues.
Second, Access Token should be sent as header, not as a URL param.
Authorization: Bearer < token>.
An OAuth token is conceptually an arbitrary-sized sequence of bytes, not characters. In URLs, it gets encoded using standard URL escaping mechanisms:
unreserved = ALPHA, DIGIT, '-', '.', '_', '~'
Everything not unreserved gets %-encoded.
I'm not sure whether you just talk about the oauth_token parameter that gets passed around. Usually, additional parameters need to be stored and transmitted as well, such as oauth_token_secret, oauth_signature, etc. Some of them have different data types, for example, oauth_timestamp is an integer representing seconds since 1970 (encoded in decimal ASCII digits).
Valid chars for OAuth token are limited by HTTP header value restrictions as OAuth token is frequently sent in HTTP header "Authorization".
Valid chars for HTTP headers are specified by https://www.rfc-editor.org/rfc/rfc7230#section-3.2.6. Alternatively you may check HTTP header validating code of some popular HTTP client libs, for example see Headers.checkNameAndValue() util of OkHttp framework: https://github.com/square/okhttp/blob/master/okhttp/src/main/java/okhttp3/Headers.java
And this is not all. I wouldn't include HTTP header separator (; and many others) and whitespace symbols (' ' and '\t') and double quote (") (see https://www.rfc-editor.org/rfc/rfc7230#section-3.2.6) as it would require to escape OAuth token before using in HTTP header. Frequently tokens are used by humans in curl test requests, and so good token generators don't add such characters. But you should check what characters may produce Oauth token generator with which your service is working before making any assumptions.
To be specific, even if Oauth spec doesn't say anything, if you are using java and mysql then it will be 16 characters as we generally generate the tokens using UUID and store it as BINARY(16) in the database. I know these details as I have recently done the development using OAuth.

Resources