OIDC, SAML, and external identity providers#

OIDC Discovery service#

Blitz Identity Provider automatically posts the OIDC Discovery service according to the settings specified in Blitz Identity Provider. As part of the service, you can specify a documentation address for the OIDC service. To specify your own documentation address, you must specify the serviceDocumentationUrl setting in the blitz.prod.local.idp.oauth settings block with the value of the documentation reference address.

Call addresses of external providers#

When implementing Blitz Identity Provider, you may need to configure calls from Blitz Identity Provider servers to external identity provider handlers not directly, but through a proxy server. In this case, it is necessary to change the default addresses of handlers of external identity providers to the addresses registered on the proxy server. To correct the handler addresses, you need to change the values of the authUri, tokenUri, dataUri settings in the corresponding blocks of the external Identity Provider settings in blitz.prod.local.idp.federation.

Example of settings for logging in through an external Google provider:

"federation" : {
  "points" : {
    "google" : [
      {
        …
        "authUri" : "https://accounts.google.com/o/oauth2/auth",
        "tokenUri" : "https://accounts.google.com/o/oauth2/token",
        "dataUri" : "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
        …
      },
      …
    ]
  }
}

External SAML provider#

Blitz Identity Provider allows you to configure login through an external identity provider running SAML 2.0.

To do this, in the blitz.prod.local.idp.federations configuration block, create an external provider saml with the following settings:

  • name is the system name of the external identity provider;

  • humanReadableName - description of the external identity provider;

  • clientId is the service provider name (EntityId) assigned to Blitz Identity Provider when registering with the external SAML Identity Provider;

  • signAuthnReq - specifies whether|project| should sign the SAML request sent to the external identity provider;

  • checkAssertionSign - determines whether to check the signature of SAML assertions received from an external identity provider (for PROD environments, it is mandatory to include signature verification);

  • credentials block with access settings to the key container used for signing requests to the SAML Identity Provider. It is configured optionally in case a separate key container is required for interaction with an external identity provider. If the setting is not specified, keys will be taken from the main keystore configured in the blitz.prod.local.idp.keystore block (in this case the name of the identity provider from the name setting will be used as alias).

    The settings are made:

    • alias is the name of the key in the container;

    • keystore is a configuration block containing the container type (type), which can be JCEKS or BKS, as well as the container path (path) and the container password (password);

  • idpMetaPath - path to the file where the external identity provider metadata (XML file with IDP metadata) is stored;

  • userMatching configuration block - specifies the rules of account matching:

    • in the type setting is an indication that the basic (value builder) account binding setting is used;

    • in the mapping setting - rules for mapping accounts from the external SAML Identity Provider to accounts in Blitz Identity Provider;

    • in the matchingRules setting - rules for migrating SAML assertions from an external identity provider to account attributes in Blitz Identity Provider;

    • requireLogInToBind - feature “Prompt the user to enter a login and password for binding if the account has not been identified “;

    • strictMatching - a feature “Require password input if account has been identified”;

    • uniqueMatching – a feature “Only one account by the configured matching rules should be found for binding”.

Example of external identity provider settings:

"federation" : {
  "points" : {
    "saml" : [
      {
       "name" : "demo-idp",
        "humanReadableName" : "External SAML IDP",
        "clientId" : "login.company.com",
        "signAuthnReq" : true,
        "checkAssertionSign" : true,
        "_credentials" : {
            "alias" : "demo-idp",
            "keyStore" : {
              "password" : "*****",
              "path" : "demo-idp-key.jks",
              "type" : "JCEKS"
            }
        },
        "idpMetaPath" : "demo-idp-metadata.xml",
        "userMatching" : {
          "type" : "builder",
          "mapping" : [
            {
              "attr" : "urn:saml:mail",
              "master" : false,
              "value" : "${email}"
            }
          ],
          "matchingRules" : [
            [
              {
                "attr" : "urn:saml:mail",
                "value" : "${email}"
              }
            ]
          ],
          "requireLogInToBind" : false,
          "strictMatching" : false,
          "uniqueMatching" : false
        }
      }
    ],
    …
  }
}

After creating the external provider settings, it is necessary to include it in the list of available external identity providers. To do this, in the blitz.prod.local.idp.login settings block in the list of authentication methods (methods) in the list of external login providers externalIdps add the external provider c fedPoint corresponding to the configured one.

Configuration example to enable an external identity provider with type saml and name demo-idp:

"login" : {
  …
  "methods" : {
    …
    "externalIdps" : {
      "idps" : [
        …
        {
          "fedPoint" : "saml:demo-idp"
        },
        …
      ],
      …
    },
    …
  },
  …
}

Customize the logo for the login button via the external login provider.