SAML Bearer Grant Type with WSO2 Identity Server 5.4.0

IS 5.4.0 has vast amount of improvements as well as features. One of the improvements we have done in 5.4.0 is handling federated users and local users explicitly in oauth/openid flows.

If you feel like this is not clear let me elaborate more. From a grant types we identify an authenticated user. This user can be either a local user or a federated user. Depending on the type of user we create either a local user or a federated user and set it to token message context.

Above is a sample of how we create a local or a federated user. In 5.4.0 we added an improvement to distinguish these two types of users in OAuth / OpenId flows. Ie if the type of authenticated user is a federated user then that particular user will never be treated as a local user. Even if there is a local user with exact same username in the local user store, those two users will be treated separately. You will not be able to access local users claims from the federated users assertion.

Let me bring an example. Suppose you have a local user with name “hasintha” in your local userstore. Also you have a SAML assertion which you took for a user with subject identifier “hasintha”. With the current implementation we absolutely have no way to identify whether this assertion is issued to the local user or not. The user depicted in the assertion may be a local user or a totally different user who comes from a different IDP. If you wonder why can’t we associate this assertion with the local user by looking at the issuer of the assertion consider the below scenarios.

  1. If you get a SMAL assertion from IS for a federated user, the SAML issuer will be identity server (resident idp), but still the user is a federated user. So we cannot assure that all SAML assertions issued by IS are issued for local users.
  2. For a SaaS application. You can bring a SAML assertion from a different tenant domain to exchange to a Oauth token. In order to get this SAML assertion validated you need to add an IDP in your SP tenant domain with foreign tenant domains certificate. Simply we cannot decide that the user is a federated user, just because the SAML issuer is configured as a separate IDP.
  3. There can be use cases like, use a trusted certificate to sign mock SAML assertions in order to use SAML bearer grant type. They exchange this SAML assertion to an OAuth token. In this case, also you need to configure a nonresident IDP. But still, the actual users are may be local.

In conclusion, by just looking at the assertion we cannot guarantee the type of user. Hence we are giving configuration to decide what the type of user is.

Following configuration element is introduced in identity.xml which resides inside <IS_HOME>/repository/conf/identity directory.

Depending on your requirement you can use any of the types of users defined in above configuration. Let’s have more insight on types of users.


The assertions which brings in have to have local formatted nameId. For an example subject identifier has to be in the format of


If the domain is not specified ‘PRIMARY’ will be taken ass the userstore domain. If the tenant domain is not specified, Service Provider tenant domain will be taken as the tenant domain. In this case the user can access local users attributes through ID token and later the user can access local user’s attributes using user info endpoint or from validation JWT.


In this case subject can be in any format. We don’t expect any special format. The important fact is, these users will not be mapped to local users. You will not be able to access local user information even if there is a user with the exact same username in the local user store.

Note — Accessing local users information from federated users were possible previously in 5.3.0. Since it shouldn’t be allowed ideally, this we have avoided this case. If you really want to access local user claims from federated users you can use the below configuration under Oauth tag in identity.xml. But this is not recommended and there are security risks associated with this.



This is the type we used way back in Identity server 5.1.0 and before. This doesn’t care about the type of user which comes in. It always tread the user as a local user with a tenant domain. It just blindly split subject from @ sign and consider the latter part as the tenant domain. We introduced this in order to protect backward compatibility. Otherwise this is also not recommended to use.