Security Tokens and Certificate Validation

In this article

    How certificates are used to validate SAML and JWT security tokens by using either the default behavior or overriding the defaults when necessary.

    It must be mentioned that the article only applies when writing .NET code and using the the SuperIdTokenHandler class from the SuperOffice.SuperID.Client.dll. If you have an alternative means of validating security tokens, this section does not apply to you.


    When your application is hosted in an environment where you do not have access or permissions to install certificates in the Windows certificate store, you must programmatically override the certificate resolver. By overriding the default certificate resolver, you get to define how the Federated Login certificate gets resolved.

    First, lets' begin with a brief review of how the SuperOffice Online certificates are normally structured and installed in a Windows certificate store. If you are more interested in learning how to install the certificates in a Windows certificate store, please read the Configuring Certificates article.

    There is one root certificate authority for SuperOffice online certificates. In the certificates download, this would be the SuperOfficeOnline.crt file. This file, the SuperOffice Online Root Certificate Authority (CA) is the root container for all other SuperOffice certificates and is, when configure in a Windows certificate store, located in the Trusted Root Certification Authorities folder.

    The next level in the chain of trust contains the environmental certificates. Environmental certificates establish a trust for their environment of responsibility, i.e. Development, Stage and Production. Each environmental certificate depends on the SuperOffice Online Root CA and cannot be used without it.

    The final level of certificates, the subject certificates, establish a trust for each environments' login services. Therefore, each environmental certificate with be a dependency on each federated login certificate. In other words, each federated login certificate depends on its' corresponding environmental certificate.


    Figure One: Certificate dependency Tree.


    This dependency tree can be observed when all three certificates are configured correctly in a Windows certificate store. Figure Two shows how this chain of trust appears in the certificates Certification Path property page. Verification begins not with the root certificate, but with the subject certificate and works up from there. In the case of SuperOffice Online security, validation responsibillity starts with the SuperOffice Online Federated Login certificate. 


    Figure Two: Correctly configured SuperOffice Online Development Federated Login certificate, SuperOfficeFederatedLogin.crt.


    Supported Trust Types

    There are three main types of Certificate Trust: Chain, Peer and None. SuperOffice Onine supports both PeerTrust and None, and that is what will be discussed for the remainder of this article. 

    Certificate Trust PeerTrust

    By default, the SuperIdTokenHandler class is configured to use PeerTrust. The SuperIdTokenHandler class, which is responsible for validating the security tokens, first looks up the source certificate thumbprint in the application settings and then tries to find a certificate in the local machines' Trusted People certificate store with a matching thumbprint. As seen in the example below, the source thumbprint must be defined in the application configuration settings. 

      <add key="SuperIdCertificate" value="16b7fb8c3f9ab06885a800c64e64c97c4ab5e98c" />


    If no certificate with a matching thumbprint is found, the ID4037 exception is thrown: "ID4037: The key needed to verify the signature could not be resolved from the following security key identifier 'SecurityKeyIdentifier.". This means that no certificate with a matching thumbprint was found. The only known reasons this might happen are:

    1. the certificates are not, as seen in Configuring Certificates, configured correctly
    2. there are hidden characters in the value field - such as an "&shy;" character.


    Default Validation of Security Token

    When unable to import certificates into a machines' certificate store, you must override the default settings. Before presenting how to override the default behavior, lets' take a look at teh default behavior of how to validate a SAML security token, and discuss the components involved.

    Security token validation will return a SuperIdToken data type, located in the SuperOffice.SuperID.Client.Tokens namespace. SuperIdToken contains string properties that are common claims, but also contains a Claims collection property that is a complete list of claims returned by SuperOffice Online. 

    Listing One: A claims container class called SuperIdToken.

    public class SuperIdToken
        public Claim[] Claims { get; }
        public string IdentityProvider { get; }
        public string Ticket { get; }
        public string NetserverUrl { get; }
        public string SystemToken { get; }
        public string Email { get; }
        public string ContextIdentifier { get; }


    Lets' take a look at what the simplest possible security token validation might look like. Listing Two shows a SAML security token validation routine.

    First a SuperIdTokenHandler is instantiated. Next its' ValidateToken method is invoked and passes a SAML token. finally it returns a SuperIdToken populated with the resulting claims. As seen in Listing One, SuperIdToken is a container around the Identity Claims that were in the SAML token.

    Listing Two: Example code to validate a SAML token. 

    public SuperIdToken ValidateToken(string token)
        var tokenHandler = new SuperIdTokenHandler();
        return tokenHandler.ValidateToken(tokenTokenType.Saml);


    As long as the three certificates are installed properly, and a correct thumbprint is defined in the SuperIdCertificate appSettings section, then the code shown in Listing Two should succeed without any problems. 

    Overriding Default Behavior of Security Token Validation

    When required to deploy your application to a cloud application server, where you have no access to the certificate store, you must override how the application will gain access to the certificate used to validate the secutity token.

    Because there are slight variances with the underlying .NET classes used for SAML vs. JWT token validation, each security token has a slightly different configuration when overriding the default validation behavior.

    SuperOfficeFederatedLogin.crt is the only certificate required when overriding the security token validation routines.

    Because the following routines only need the one subject certificate to validate the security token, your applciation needs a way to short curcuit the PeerTrust validation, or certificate dependencies. It does this by setting the CertificateValidator property to None.

    tokenHandler.CertificateValidator = X509CertificateValidator.None;

    Setting the CertificateValidator to None allows the certificate routines to bypass certificate validation, and just focus on validating the SAML or JWT security token with the provided certificate.

    For both examples below, we assume your application has an App_Data folder containing the SuperOfficeFederatedLogin.crt certificate. 


    SAML Validation

    For SAML tokens, the application must override the IssueTokenResolver property with a class that knows how to resolve certificates. SuperOffice providers the CertificateFileCertificateStoreTokenResolver class. Its' constructor accepts a path where it will search for certificates. It searchs for certificates with a .crt, .cer or .pfx file extension.

    Listing Three: How to override the IssuerTokenResolver and CertificateValidator properties.

    public SuperIdToken ValidateToken(string token)
        var tokenHandler = new SuperIdTokenHandler();
    tokenHandler.IssuerTokenResolver = new CertificateFileCertificateStoreTokenResolver(
    tokenHandler.CertificateValidator = X509CertificateValidator.None;     return tokenHandler.ValidateToken(tokenTokenType.Saml); }

    As long as the token is of type SAML, and the certificate resides in the App_Data folder, the ValidateToken method will return a SuperIdToken populated with all the claims returned by SuperOffice Online.


    JWT Validation

    For processing JWT security tokens, the application must override the token handlers JwtIssuerSigningCertificate property. This expects an X509Certificate2 type. The  X509Certificate2 constructor accepts a file name argument, and is the file name of the certificate that will be used to validate the security token. Again, assuming your application has an App_Data folder that contains the SuperOfficeFederatedLogin.crt certificate, that full file path is passed into the constructor. The token handler CertificateValidator property is set to None just as before, and then the token handler can call its' ValidateToken method. 

    Listing Four: How to override the JwtIssuerSigningCertificate and CertificateValidator properties.

    public SuperIdToken ValidateToken(string token)
        var tokenHandler = new SuperIdTokenHandler();
        tokenHandler.JwtIssuerSigningCertificate = new X509Certificate2(
    HttpContext.Current.Server.MapPath("~/App_Data/"+ "SuperOfficeFederatedLogin.crt");
        tokenHandler.CertificateValidator = X509CertificateValidator.None;     return tokenHandler.ValidateToken(tokenTokenType.Jwt); }

    As long as the token is of type JWT, the ValidateToken method will return a SuperIdToken populated with all the claims returned by SuperOffice Online.



    Whether deploying an application to an environment where there is complete control over certificates, or a restricted one, SuperOffice API's support the ability to configure your certificates for security token validation for both cases.

    The key difference is that you will need all three certificates for the default PeerTrust validation, and only one certificate when you need to override the default behavior.