[OPENAM-13978] Session Upgrade - AuthLevel format changes Created: 14/Nov/18  Updated: 15/Apr/20  Resolved: 18/Jan/19

Status: Resolved
Project: OpenAM
Component/s: authentication, session
Affects Version/s: 5.5.1, 6.0.0,,,,,,,
Fix Version/s: 13.5.3, 14.1.2, 6.5.1, 6.0.1, 5.5.2, 7.0.0

Type: Bug Priority: Major
Reporter: Tasos Kampas Assignee: Lawrence Yarham
Resolution: Fixed Votes: 0
Labels: EDISON
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
duplicates OPENAM-9663 Inconsistent format for AuthLevel att... Resolved
duplicates OPENAM-11384 Auth Level value for step up sessions... Closed
is related to OPENAM-14257 Session Upgrade - AuthType, Service &... Open
Target Version/s:
Sprint: AM Sustaining Sprint 57, AM Sustaining Sprint 58, AM Sustaining Sprint 59
Story Points: 2
Needs backport:
Support Ticket IDs:
Verified Version/s:
Needs QA verification:
Functional tests:
Are the reproduction steps defined?:
Yes and I used the same an in the description


Bug description

AuthLevel format changes after a session upgrade.

How to reproduce the issue

Create 2 chains:


DataStore1 AuthLevel:5

DataStore2 AuthLevel:10

Insert AuthLevel in Session Property Whitelist Service

1. Log in using chainA, request a getSessionInfo:

"properties": {
 "AMCtxId": "0815c6e5-21e2-4d34-bfb6-8d43070bc9a5-10755",
 "AuthLevel": "5"

2. Now re-login using the chanB as part of a session upgrade. Call the getSessionInfo:

"properties": {
 "AMCtxId": "0815c6e5-21e2-4d34-bfb6-8d43070bc9a5-10881",
 "AuthLevel": "/:10"

Similar closed bugs:

  1. -OPENAM-8188-
  2. -OPENAM-9663-

We need AuthLevel format to be defined and consistent.

Expected behaviour
AuthLevel to keep its format
Current behaviour
AuthLevel format changes


Comment by Jonathan Thomas [ 11/Dec/18 ]

I think this is more or less a duplicate of https://bugster.forgerock.org/jira/browse/OPENAM-9663 and assuming this change in format on session upgrade has been the been the case for some time.

Quote from OPENAM-9663

To the best of my knowledge the format of the AuthLevel session property is not documented. In light of this I believe users should not make any assumptions on the format/value of this session property.

As mentioned in OPENAM-9663 and OPENAM-4080 the AuthLevel attribute is not defined.

To progress this we should decide whether we continue with
1) Continue storing a realm qualified value and then convert to an int when consumed
2) Decide on a format change if the realm qualifier is not needed.
However I think that should be a documented major version change as may affect existing integrations.

Comment by Daniel Franke [ 07/Jan/19 ]



nice try but:

  1. This ticket covers the documentation of the session property format at all. The linked ticket covers only the SAML2 case
  2. The statement from Peter Major in OPENAM-9663 seems to be wrong as usage of session property is documented under https://backstage.forgerock.com/knowledge/kb/book/b93241706#authlevel and if someone would have searched "authentication level" in authorization guide (https://backstage.forgerock.com/docs/am/6/authorization-guide/#what-is-authz-decision), you could get the impression that it should be a number.
  3. When you see the bugs which were opened as the auth level changes form a simple number to format <realm>:<auth level>, you can get the impression that also you developers have defined auth level as a number before:



Comment by Peter Major [X] (Inactive) [ 07/Jan/19 ]


  • the knowledge base article talks about the auth level session property, but it does not describe its actual format. The example value used there is also showing 0 as a string, not as a number.
  • The authorization guide talks about authentication level as a generic concept, it does not discuss how AM internally tracks the current session's authentication level.

Now to the constructive part:
I have to very much agree that there is definitely confusion around the session property's value format. The fact that realm qualification isn't always done, pretty much forces every API user to deal with both possible formats, and as you are highlighting it, we had several cases where we've been updating the auth level consuming code to deal with this (OPENAM-4080 and OPENAM-12173 are good example for this).
What's making it more annoying is the fact that the realm qualification of the authentication level adds exactly zero additional value. Session upgrade cannot cross realms and the realm is already there in the session under the Organization session property. Having the realm qualifier in the authentication level just makes the session bigger for no apparent reason.

I'm not sure I fully agree with the compatibility concerns from our part:

  • when the session is never updated, the authentication level is a number written down as a string. After we get rid of the realm qualification, it would be always a number.
  • when the session gets upgraded, then the API consumers would have to deal with both formats already, probably very much like AM does today.
  • the only issue is when the session is always in an upgraded state by the time it gets consumed. In this case the parsing would most likely fail. I think it's relatively safe to assume that this kind of usage is less likely than the other two combined.

All in all, I think we should revisit our viewpoint on the AuthLevel property's format and consider making it consistent (if we want to go down on the Least Astonishment Principle path, the authentication level should be a number, not a realm qualified string).

NB: the REST endpoints should still return the AuthLevel as a string value (so "0"), because we don't really have session property schema/etc to describe the type of the property values.
cc Jonathan Thomas

Comment by Jonathan Thomas [ 08/Jan/19 ]

Based on last comments from Peter - we'll reopen and look into creating a standard format.

Comment by Daniel Franke [ 08/Jan/19 ]

Hello @peter.major,


The knowledge article says "authentication level".

You are right that the mentioned passage in authorization guide does not mention how AM handles it internally. But your glossary gives a clear definition for the term "authentication level" (https://backstage.forgerock.com/docs/am/6.5/authentication-guide/#openam-glossary):

"Positive integer associated with an authentication module, usually used to require success with more stringent authentication measures when requesting resources requiring special protection."


It also gives more explanation of the authentication level and explains how am handles it compares it etc. https://backstage.forgerock.com/docs/am/6.5/authentication-guide/#about-authentication-levels .

Also in authentication modules (auth nodes) you have to define and use it like an integer.

So inventing a new definition of the term for the kb article is a little bit childish especially as all other definitions and explanations are consistent to the definition in the glossary and there is now documentation of another definition/interpretation.

If I would be nitpicking I could say sorry, but it is defined as a positive integer and so string representation in json is not ok, but we are not in the kindergarten and string representation is ok for us (beside the fact that the definition for this is not absolutely clear and changing the getSessionInfo endpoint for this single session property would introtuce new bugs).

What is also not ok is that you are saying that the authentication level format is not defined at all and that you do not want to define it.

Especially as the way how to get it (kb-article) is defined and a definition of the "authentication level" is given (positive integer). 


So In my opinion this here is a bug and also mentioned problem with authlevel in saml2 assetion (OPENAM-9663) is a bug. What makes the whole problem ridiculous is that also your developers used the same definition of the authentication level (mentioned list of bugs above). And instead of fixing the representation in the session after session upgrade ("10" instead of "/:10)  you decided to fix all other endpoints. 


But this are only my 2 cents.


I am happy that you decided to make it more consistent and hope that you will define the output of all endpoints (if you are still thinking that ther are different definitions of "authentication level"


Comment by Peter Major [X] (Inactive) [ 08/Jan/19 ]

My mistake, I don't really read the documentation.
This issue has been reopened, so looks like it's back on track now.

Comment by Tasos Kampas [ 15/Jan/19 ]

The same is happening with the "AuthType", "Service" and "moduleAuthTime" session properties as well:

<Property name=“AuthType” value=“/:DataStore|DataStore|http”></Property>
<Property name=“Service” value=“/:ldapService|test”></Property>
<Property name="moduleAuthTime" value="DataStore+2019-01-15T16:42:56Z|http+2019-01-15T16:41:59Z|/:DataStore+2019-01-15T16:41:59Z"></Property>

I will raise a different JIRA (OPENAM-14257)

Comment by Ľubomír Mlích [ 22/Mar/19 ]

Reproduced in AM 6.5.0 - I see

"AuthLevel": "/:10"

And in ForgeRock Access Management 6.5.1-RC2 Build 6e42f86d08 (2019-March-20 19:43) I see this as fixed, there is:

"AuthLevel": "10"
Generated at Sat Nov 28 10:57:51 UTC 2020 using Jira 7.13.12#713012-sha1:6e07c38070d5191bbf7353952ed38f111754533a.