OrchardCore.OpenId
¶
OpenID Connect Module¶
OrchardCore.OpenId
provides the following features:
- Core Components
- Entity Framework Core Stores
- Authorization Server
- Management Interface
- Token Validation
- OIDC Client
Core Components¶
Registers the core components used by the OpenID module.
Entity Framework Core Stores¶
Provides an Entity Framework Core 2.x adapter for the OpenID module.
Management Interface¶
Allows adding, editing and removing the registered applications.
Authorization Server¶
Enables authentication of external applications using the OpenID Connect/OAuth 2.0 standards.
It is based on the OpenIddict
library allowing.
Orchard Core to act as identity provider to support token authentication without the need of an external identity provider.
- Orchard Core can also be used as an identity provider for centralizing the user access permissions to external applications.
- Orchard Core services.
- The authorization server feature maintains its own private JWT/validation handler instance for the userinfo API endpoint. This way, you don't have to enable the token validation feature for current tenant.
Flows supported: code/implicit/hybrid flows and client credentials/resource owner password grants.
Configuration¶
Configuration can be set through the OpenID Connect settings menu in the admin dashboard and also through a recipe step.
Available settings are:
- Testing Mode: Enabling Testing mode, removes the need of providing a certificate for signing tokens providing an ephemeral key. Also removes the requirement of using HTTPS for issuing tokens.
- Token Format: there are two options:
- JWT: This format uses signed JWT standard tokens (not encrypted). It requires that the SSL certificate being used is accepted as a trusted certificate by the client.
- Encrypted: This format uses non-standard opaque tokens encrypted by the ASP.NET data protection block. It doesn't require the client to accept the SSL certificate as a trusted certificate.
- Authority: Orchard URL used by Orchard to act as an identity server.
- Audiences: URLs of the resource servers for which the identity server issues valid JWT tokens.
- Certificate Store Location: CurrentUser/LocalMachine https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storelocation(v=vs.110).aspx
- Certificate Store Name: AddressBook/AuthRootCertificateAuthority/Disallowed/My/Root/TrustedPeople/TrustedPublisher https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storename(v=vs.110).aspx
- Certificate Thumbprint: The thumbprint of the certificate (it is recommended to not use same certificate that is being used for SSL).
- Enable Token Endpoint.
- Enable Authorization Endpoint.
- Enable Logout Endpoint.
- Enable User Info Endpoint.
- Allow Password Flow: It requires that the Token Endpoint is enabled. More info at https://tools.ietf.org/html/rfc6749#section-1.3.3
- Allow Client Credentials Flow: It requires that the Token Endpoint is enabled. More info at https://tools.ietf.org/html/rfc6749#section-1.3.4
- Allow Authorization Code Flow: It requires that the Authorization and Token Endpoints are enabled. More info at http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
- Allow Implicit Flow: It requires that the Authorization Endpoint is enabled. More info at http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth
- Allow Refresh Token Flow: It allows to refresh access token using a refresh token. It can be used in combination with Password Flow, Authorization Code Flow and Hybrid Flow. More info at http://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
A sample of OpenID Connect Settings recipe step:
{ "name": "OpenIdServerSettings", "TestingModeEnabled": false, "AccessTokenFormat": "JWT", //JWT or Encrypted "Authority": "https://www.orchardproject.net", "Audiences": ["https://www.orchardproject.net","https://orchardharvest.org/"], "CertificateStoreLocation": "LocalMachine", //More info: https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storelocation(v=vs.110).aspx "CertificateStoreName": "My", //More info: https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storename(v=vs.110).aspx "CertificateThumbprint": "27CCA66EF38EF46CD9022431FB1FF0F2DF5CA1D7", "EnableTokenEndpoint": true, "EnableAuthorizationEndpoint": false, "EnableLogoutEndpoint": true, "EnableUserInfoEndpoint": true, "AllowPasswordFlow": true, "AllowClientCredentialsFlow": false, "AllowAuthorizationCodeFlow": false, "AllowRefreshTokenFlow": false, "AllowImplicitFlow": false }
Client OpenID Connect Apps Configuration¶
OpenID Connect apps can be set through OpenID Connect Apps menu in the admin dashboard (through the Management Interface feature) and also through a recipe step.
OpenID Connect apps require the following configuration.
- Id: Unique identifier.
- Client Id: Client identifier of the application. It has to be provided by a client when requesting a valid token.
- Display Name: Display name associated with the current application.
- Type: There are two options:
- Confidential: Confidential applications MUST send their client secret when communicating with the token and revocation endpoints. This guarantees that only the legit client can exchange an authorization code or get a refresh token.
- Public: Public applications don't use client secret on their communications.
- Client Secret: Client secret is a password associated with the application. It will be required when the application is configured as Confidential.
- Flows: If general OpenID Connect settings allow this flow, an app can also enable this flow.
- Allow Password Flow: It requires that the Token Endpoint is enabled. More info at https://tools.ietf.org/html/rfc6749#section-1.3.3
- Allow Client Credentials Flow: It requires that the Token Endpoint is enabled. More info at https://tools.ietf.org/html/rfc6749#section-1.3.4
- Allow Authorization Code Flow: It requires that the Authorization and Token Endpoints are enabled. More info at http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
- Allow Implicit Flow: It requires that the Authorization Endpoint is enabled. More info at http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth
- Allow Refresh Token Flow: It allows to refresh access token using a refresh token. It can be used in combination with Password Flow, Authorization Code Flow and Hybrid Flow. More info at http://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
- Normalized RoleNames: This configuration is only required if Client Credentials Flow is enabled. It determines the roles assigned to the app when it is authenticated using that flow.
- Redirect Options: Those options are only required when Implicit Flow, Authorization Code Flow or Allow Hybrid Flow is required.
- Logout Redirect Uri: logout callback URL.
- Redirect Uri: callback URL.
- Skip Consent: sets whether a consent form has to be completed by the user after log in.
A sample of OpenID Connect App recipe step:
{ "name": "openidapplication", "ClientId": "openidtest", "DisplayName": "Open Id Test", "Type": "Confidential", "ClientSecret": "MyPassword", "EnableTokenEndpoint": true, "EnableAuthorizationEndpoint": false, "EnableLogoutEndpoint": true, "EnableUserInfoEndpoint": true, "AllowPasswordFlow": true, "AllowClientCredentialsFlow": false, "AllowAuthorizationCodeFlow": false, "AllowRefreshTokenFlow": false, "AllowImplicitFlow": false }
Configuring Certificates¶
Windows / IIS¶
Several tools are available for generating a signing certificate on Windows and/or IIS, for example:
- IIS Server Manager (offers limited control)
- Server Certificates
- Create Self-Signed Certificate
- PowerShell (offers full control)
New-SelfSignedCertificate
, for example:
# See https://technet.microsoft.com/en-us/itpro/powershell/windows/pkiclient/new-selfsignedcertificate New-SelfSignedCertificate ` -Subject "connect.example.com" ` -FriendlyName "Example.com Signing Certificate" ` -CertStoreLocation "cert:\LocalMachine\My" ` -KeySpec Signature ` -KeyUsage DigitalSignature ` -KeyUsageProperty Sign ` -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1") ` -KeyExportPolicy NonExportable ` -KeyAlgorithm RSA ` -KeyLength 4096 ` -HashAlgorithm SHA256 ` -NotAfter (Get-Date).AddDays(825) ` -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider"
This snippet must be run as admin. It generates a 4096-bit signing certificate, stores it in the machine store and returns the certificate's thumbprint, which you need in the OpenID Connect Settings recipe or when exporting the certificate through PowerShell. You should update this example according to your requirements!
In multi-node environments consider creating the certificate with -KeyExportPolicy Exportable
, then export the certificate (PFX) to a secure location, using the MMC Certificates Snap-In or PowerShell Export-PfxCertificate
, and subsequently import the certificate on each node as non-exportable, which is the default when using Import-PfxCertificate
. For example:
# See https://technet.microsoft.com/en-us/itpro/powershell/windows/pkiclient/export-pfxcertificate # Run this on the machine where the certificate was generated: $mypwd = ConvertTo-SecureString -String "MySecretPassword123" -Force -AsPlainText Export-PfxCertificate -FilePath C:\securelocation\connect.example.com.pfx cert:\localMachine\my\thumbprintfromnewselfsignedcertificate -Password $mypwd # See https://technet.microsoft.com/en-us/itpro/powershell/windows/pkiclient/import-pfxcertificate # Run this on the target node: $mypwd = ConvertTo-SecureString -String "MySecretPassword123" -Force -AsPlainText Import-PfxCertificate -FilePath C:\securelocation\connect.example.com.pfx cert:\localMachine\my -Password $mypwd
Important: In order for the OrchardCore.OpenId
module to use the certificate's keys for signing, it requires Read
access to the certificate in the store. This can be granted in various ways, for example:
MMC.exe
- Add Snap-In 'Certificates' for Computer Account
- Right-Click relevant certificate and select All Tasks, Manage Private Keys
- Add the relevant identity (e.g. IIS AppPool\PoolName)
- Add
- Advanced
- Locations: Choose iis server machine name
- Find Now
- Search Results: Choose your iisServerMachineName\IIS_IUSRS (just one example)
- OK
- Check Allow Read under Permissions
WinHttpCertCfg.exe
(grants Full Control)- For example:
winhttpcertcfg -g -c LOCAL_MACHINE\My -s connect.example.com -a AppPoolIdentityName
https://msdn.microsoft.com/en-us/library/windows/desktop/aa384088(v=vs.85).aspx
- For example:
Use the Certificate in Azure¶
To use the certificate on an Azure hosted site.
- Upload the certificate to the 'TLS/SSL settings' page of the site Azure portal page.
- Add a new entry to the Azure site setting page with the following:
- Key: WEBSITE_LOAD_CERTIFICATES
- Value: [Thumbprint of the certificate]
- Select the certificate under
CurrentUser
>My
certificate store.
Token Validation¶
- Validates tokens issued by the Orchard OpenID server
- Configure the validation feature to transparently use the server configuration of another tenant, which has the authorization server feature enabled.
- Validates token by a remote server supporting JWT and OpenID Connect discovery.
OIDC Client¶
Authenticates users from an external OpenID Connect identity provider. If the site allows to register new users, a local user is linked and the external login is linked. If an "email" claim is received, and a local user is found, then the external login is linked to that account, after authenticating.
OpenId Configuration¶
Configuration can be set through the OpenID Connect settings menu in the admin dashboard and also through a recipe step.
Available settings are:
- Display Name: Display name of the IdP. It is shown in the login form.
- Authority: Authority to use when making OpenIdConnect calls.
- ClientId: The
client_id
part of the query. - CallbackPath: The request path within the application's base path where the user agent will be returned after sign out from the identity provider. See
post_logout_redirect_uri
from http://openid.net/specs/openid-connect-session-1_0.html#RedirectionAfterLogout - SignedOut CallbackPath: the callback endpoint for signout. Defaults to
/signout-callback-oidc
. - SignedOut Redirect Uri: The URI where the user agent will be redirected to after application is signed out from the identity provider. The redirect will happen after the
SignedOutCallbackPath
is invoked. - Scopes: Extra scopes except openid and profile.
- Response Mode: Configure Response Mode see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse. If fragment or query only Code Authentication Flow is allowed.
- Supported Flows: Select one of the OIDC flows:
- Code Authentication Flow (see: http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
- Hybrid Authentication Flow (see: http://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest)
- Use
code id_token
response type (example: http://openid.net/specs/openid-connect-core-1_0.html#code-id_token-tokenExample) - Use
code id_token token
response type (example: http://openid.net/specs/openid-connect-core-1_0.html#code-id_token-tokenExample) - Use
code token
response type (example: http://openid.net/specs/openid-connect-core-1_0.html#code-tokenExample)
- Use
- Implicit Authentication Flow (see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthRequest)
- Use
id_token
response type (example: http://openid.net/specs/openid-connect-core-1_0.html#id_tokenExample) - Use
id_token token
response type (example: http://openid.net/specs/openid-connect-core-1_0.html#id_token-tokenExample)
- Use
- Client Secret: It is used with one of the 'confidential' flows, code or hybrid.
A sample of OpenID Connect Client Settings recipe step:
{ "name": "OpenIdClientSettings", "Authority": "http://localhost:44300/t1", "DisplayName": "Orchard (t1) IdP", "ClientId": "orchard_t2", "CallbackPath": "/signin-oidc", "SignedOutCallbackPath": "/signout-callback-oidc", "Scopes": "email phone", "ResponseMode": "form_post", "ResponseType": "code id_token", "ClientSecret": "secret" }
CREDITS¶
OpenIddict¶
https://github.com/openiddict
License under Apache License 2.0