Test IdP - kmd-identity/documentation GitHub Wiki

The Test IdP is a service which we provide for you to test how your client application handles login flows. This includes three major use cases:

  • Allow SAML client applications to test signing, decryption and validation during log-in and log-out flows without any configuration on KMD Identity.
  • Allow SAML client applications to test wrong/faulty/hacking attempts by having Test IdP simulate wrong signature/issuer/audience in SAML response.
  • Allow SAML client applications to test log-ins with a set of custom claims defined by you.

The service only supports SAML flows, so OpenID applications are currently not supported. Feel free to contact KMD Identity and express your interest if this is something you need.

To illustrate how the service can be used, we will walk you through setting up one of our test applications to login using the Test IdP.

The first step will be to configure the KMD.Identity.TestApplications.SAML.MVCCore project to use the SAML metadata endpoint exposed by the Test IdP. To do this, you must update the IdPMetadata endpoint in the appsettings.json file of that project to have this value:

https://testidp.identity.kmd.dk/saml/metadata/postLoginUrl/cG9zdHxodHRwczovL2xvY2FsaG9zdDo0NDM1MC9BdXRoL0Fzc2VydGlvbkNvbnN1bWVyU2VydmljZQ==/postLogoutUrl/cG9zdHxodHRwczovL2xvY2FsaG9zdDo0NDM1MC9BdXRoL0xvZ2dlZE91dA==/interactive/true/idpmode/standard

In the above url, the two url encoded parts are the login and a logout endpoints for the localhost:44350 application. It should be the address where the test application is running. If you do not want to use custom claims, just replace true with false at the end.

The endpoint you just configured is specific to our test application. To help you create a correct URL for your own client system (and to avoid having to manually url encode the endpoints), we provide a helper page. See the Metadata URL Generator section below for more information on where to find and how to use this tool.

Once the configuration has been updated the application is configured to use the Test IdP and you just need to start the application. As it starts you will see a login link which will initiate the login flow that you have configured.

Metadata URL Generator

For the Test IdP to know how to connect to your client system you must configure the URL where it looks for the SAML metadata. The parameters on the URL allows you to modify the content of the generated metadata xml document without having to contact KMD Identity support - no configuration is required on our end for this to work.

To help you construct this url in the correct format, you can go to the Test IdP Metadata URL Generator.

The URL generator requires you to consider three things:

  1. The post login URL - A URL which is called on completion of the login flow to provide the client system with information about the logged in user. The request to this endpoint will contain the SAML response.
  2. The post logout URL - A URL which is called when a logout request is triggered for the user.
  3. Interactive mode - If this is enabled, an additional step is added to the login flow where you can add your own custom claims, which will be present in the SAML response. See the Adding Custom Claims section for guidance on using the custom claims page.

For the two URLs you will have to choose between a GET and a POST based flow. The GET flow will redirect the user to the post login/logout URL while the POST flow will submit a POST request to the same URL. Which approach is right for you depends on how you have implemented the SAML flow in your application.

Adding Custom Claims

If you enable interactive mode for the login flow then users will be presented with a form where they can define up to 15 claims which will be present in the SAML Response. It is up to you to determine which claims make sense. There are 2 major requirements to be aware of, however:

  1. There must always be a claim with the type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier. This has special meaning to the login flow as the unique identifier representing the user.
  2. There must be at least one additional claim, but neither its type or value are important.

Claims without both a type and a value will be ignored.

Saving and Loading Claims

You may want to reuse the same set of claims between sessions and the form provides functionality to make this easy. Pressing the Save Claim Set button will prompt you to give a name for the set you want to save after which your claims will be saved under that name. Any further changes to the claims will be saved automatically.

If you want to load a previously saved claim set, press the Load Claim Set button. This button will be disabled when there are no claim sets available. Note that claim sets are saved using the local storage of the browser being used. This means that you cannot access claims saved using a different browser or saved by a different user on the machine.

When you have saved or loaded a named claim set, a menu bar will appear along with the name of the set. As long as this menu is present, it indicates that you are working on a named set. As mentioned before, changes to the claims will automatically be saved. The menu for the named claim set allows you to either rename the set or delete it. If you want to start a new claim set without dropping the current one, you can press the New Claim Set button (it replaces the Save Claim Set button while working on a saved claim set).

Generating Incorrect SAML Responses

A central part of testing your SAML flow implementation is to verify that you validate the response. We support a number of ways for you to instruct the Test IdP to generate wrong SAML responses, which you can then validate on your end.

  • Generate Wrong Signature: When setting up the SAML login flow it is important to verify that the SAML response is signed with the expected certificate, as declared in the metadata file. Otherwise, you leave yourself open to man-in-the-middle attacks. Checking the "Generate Wrong Signature" checkbox will cause the signature in the SAML response to be incorrect.
  • Generate Wrong Issuer: An additional step in verifying the validity of the response is to check that the issuer has the expected value. Checking the "Generate Wrong Issuer" checkbox will cause the issuer in the SAML response to be incorrect.
  • Generate Wrong Audience: Finally, you should verify that your system is the intended recipient of the SAML response. Checking the "Generate Wrong Audience" checkbox will cause the audience in the SAML response to be incorrect.

Claim Actions

We provide a few extra convenience functions for editing claims which can be accessed through the lightning menu next the the claim Type field.

  • Base64 encode value: This will replace the claim value with the base64 encoded version of the value. This can be used to simulate certain situations where base64 encoded values are expected, such as claims from Context Handler.
  • Base64 decode value: This will replace the claim value with the base64 decoded version of the value. If the value is not encoded then the action does not change the value.