IdentityServer was designed with extensibility in mind. And since the question how to do that comes up quite frequently, here’s a overview to get you started.
Certain parts of IdSrv that we thought might need to be extended or customized are abstracted using interfaces – e.g. how to store and retrieve certificates or how to authenticate a user. You can find all the interface in the Core project’s Repositories folder.
Configuration data storage & retrieval
- IConfigurationRepository (general and protocols configuration)
- IClientCertificateRepository (X.509 client certificates and their mappings to user accounts)
- IClientRepository (OAuth2 clients)
- IDelegationRepository (WS-Trust identity delegation mappings)
- IIdentityProviderRepository (WS* and OAuth2 identity providers)
- IRelyingPartyRepository (relying parties and resources)
Runtime data access
- ICodeTokenRepository (OAuth2 authorization codes and refresh token handling)
- IClaimsRepository (claims retrieval for token generation)
- IClaimsTransformationRulesRepository (claims transformation logic for external identity providers)
- IUserManagementRepository (user management)
- IUserRepository (user authentication)
All these extensibility points are wired up using MEF. MEF in turn reads from the repositories.config file in the WebSite project. So in other words, when you want to customize a certain part of IdSrv, implement the right interface and replace the default implementation with yours in repositories.config.
Most common scenario: customize authentication and claims retrieval
By far the most common task is to adapt IdSrv to an existing credential and attribute store. That’s actually quite easy to achieve.
The IUserRepository interface takes care of authentication:
public interface IUserRepository
bool ValidateUser(string userName, string password);
bool ValidateUser(X509Certificate2 clientCertificate, out string userName);
IEnumerable<string> GetRoles(string userName);
ValidateUser does either username/password or client certificate based authentication. You only need to implement what you want to support.
GetRoles return roles for IdSrv internal authorization, e.g. users (that can request tokens) have to be in the IdentityServerUsers role. Admins (that can administer IdSrv but can’t request tokens) have to be in the IdentityServerAdministrators role.
The IClaimsRepository interface abstracts claims generation and the corresponding metadata:
public interface IClaimsRepository
IEnumerable<Claim> GetClaims(ClaimsPrincipal principal,
GetClaims returns a list of claims for a given principal. The requestDetails parameter has information about the relying party/resource the token is for.
GetSupportClaimTypes is used to augment the WS-Federation metadata document with the supported claim types.
PS. Yes I am aware that these extensibility points are not really repositories. Historically they were named like this, and that’s now the way it is ;)