[Development Guides Home](/guides) >> [Guide to External Authentication](/guides/guide-to-external-authentication) # Guide to External Authentication - OpenID Connect ## Introduction External authentication allows your server's users to log in to WHM, cPanel, and Webmail through OpenID Connect-compliant identity providers. The OpenID Connect Provider Module configures a server to connect to and authenticate through the identity provider. Create the identity provider module in the `/var/cpanel/perl/Cpanel/Security/Authn/Provider/` directory and use the `Cpanel::Security::Authn::Provider::OpenIdConnectBase` base class. Note: Additional examples that demonstrate other methods are available in the `/usr/local/cpanel/Cpanel/Security/Authn/Provider/` directory with the `.sample` file extension. Warning: After you install the identity provider module, you must obtain credentials from that identity provider and then use WHM's [*Manage External Authentications*](https://docs.cpanel.net/whm/security-center/manage-external-authentications/) interface (*WHM >> Home >> Security Center >> Manage External Authentications*) to configure the identity provider module with those credentials. ## OpenID Connect's authentication chain When you use an identity provider, the system performs the following steps: 1. The cPanel service login interface displays a list of configured and enabled identity providers. 2. The user clicks the desired identity provider. 3. The browser redirects the user to the login interface for the identity provider. 4. The user enters their credentials for the identity provider. 5. The browser returns the user to the cPanel service login interface. 6. If the user has not yet associated their authentication credentials with the account in cPanel's *Password & Security* interface (*cPanel >> Home >> Preferences >> Password & Security*), the server asks for their local server credentials. 7. If the user has associated their authentication credentials with the account, the server will automatically log them in to the cPanel service. ## OpenID Connect's provider methods The tables below contain the required, recommended, and optional methods. ### Required Warning: You **must** configure the following methods in the `Cpanel::Security::Authn::Provider::OpenIdConnectBase` base class. If you do not configure a required method, it will die with a `Cpanel::Exception::NotImplemented` exception. | Method name | Type | Description | Possible values | Example | | --- | --- | --- | --- | --- | | `_DISPLAY_NAME` | *string* | The identity provider's friendly name. cPanel & WHM interfaces display this value. | A valid string. | `Izzy` | | `_PROVIDER_NAME` | *string* | The identity provider's system name.This method must be unique among the installed OpenID Connect identity providers.This method should consist of lower-case letters, numbers, dashes, periods, and underscores in 7-bit ASCII. We recommend that you enter the identity provider name in lower case in order to avoid case conversion issues. | A valid string in lower case. | `izzy` | | `_WELL_KNOWN_CONFIG_URI` | *string* | The well-known configuration URI of the OpenID Connect implementation. The system uses the configuration to discover the endpoints to use in the OpenID Connect exchange.The system retrieves the configuration on demand and caches it for 24 hours.Upon receipt of a fresh configuration file, the system will update the changes in the remote endpoints for OpenID Connect authorization.For more information about well-known configuration URIs, read RFC 5785. | A valid URI. | `https://accounts.izzy.com/.well-known/openid-configuration` | ### Suggested We **strongly** recommend that you update the following methods in order to properly label your OpenID Connect implementation. | Method name | Type | Description | Possible values | Example | | --- | --- | --- | --- | --- | | `_BUTTON_COLOR` | *string* | The background color of the button on the cPanel interface. This value defaults to `cccccc`. | A valid RGB hexadecimal value. | `dd4b39` | | `_BUTTON_ICON` | *string* | The icon file to display in the button on the cPanel login interface. This value defaults to empty string. | A valid Base64-encoded image file. | (see example in above code) | | `_BUTTON_ICON_TYPE` | *string* | The icon file's MIME type. | A valid image format's MIME type. | `image/svg+xml` | | `_BUTTON_LABEL` | *string* | The text label of the login icon on the cPanel login interface. This value defaults to `Log in with an OpenID Connect`. | A valid string. | `Log in with Izzy account` | | `_BUTTON_TEXT_COLOR` | *string* | The color of the text label on the cPanel login interface. This value defaults to `000000`. | A valid RGB hexadecimal color value. | `ffffff` | | `_DOCUMENTATION_URL` | *string* | The public URL of the OpenID implementation's documentation at the openid.net website. | A valid URL. | `https://developers.izzy.com/identity/protocols/OpenIDConnect` | ### Other The following methods may not precisely conform to the specification of the OpenID Connect identity provider's protocol. Also, your identity provider may include newer or custom features that you wish to use. | Method name | Type | Description | Possible values | Example | | --- | --- | --- | --- | --- | | `_CAN_VERIFY` | *Boolean* | Whether the OpenID Connect identity provider supports signature verification of the identity tokens that the authorization server sends. This value defaults to `1`. | `1` — The authorization server supports signature verification.`0` — The authorization server does not support signature verification. | `1` | | `_CONFIG` | *hash* | A hash of the identity provider's configuration settings. This hash contains the `id`, `secret`, `authorize_url`, `access_token_uri`, `user_info_uri`, and `redirect_uris` parameters. | | | | `id` | *string* | The client ID that you received when you registered your application with the authorization server. For more information, read For more information, read RFC-6749. | A valid string. | `123456789012345678901` | | `secret` | *string* | The client secret that you received when you registered your application with the authorization server. For more information, read RFC-6749. | A valid string. | `Victoria` | | `authorize_url` | *string* | The URI to the authorization endpoint of the authentication server.This value defaults to the URI that the system retrieves from the well-known configuration.For more information, read OpenID's Authorization Endpoint documentation. | A valid URI. | `http://authorize.izzy.com/` | | `access_token_uri` | *string* | The URI to the token endpoint of the authorization server. This value defaults to the URI that the system retrieves from the well-known configuration.For more information, read OpenID's Token Endpoint documentation. | A valid URI. | `https://accounts.izzy.com/tokens/` | | `user_info_uri` | *string* | The URI to the user_info endpoint of the authorization server. This value defaults to the URI that the system retrieves from the well-known configuration.For more information, read OpenID's User Info documentation. | A valid URI. | `https://accounts.izzy.com/user_info/` | | `redirect_uris` | *array of strings* | A list of valid redirection URIs that you sent when you registered your application to the authorization server. This value defaults to the values that the WHM configuration interface generates.For more information, read RFC-6749. | An array of valid URIs. | `http://izzy.com/` | | `_CONFIG_FIELDS` | *hash of hashes* | A hash of the identity provider's configuration fields. This hash contains the `field_name` parameter. | | | | `field_name` | *hash* | A hash of a configuration field's parameters. The hash uses the configuration field's name as a parameter name. | (varies) | | | `label` | *string* | The configuration entry's display name. | (varies) | | | `description` | *string* | The configuration entry's description. | (varies) | | | `value` | *string* | The configuration entry's default value, which will be `undef` if the identity provider has not set a value . | (varies) | | | `_DISPLAY_CONFIG` | *hash* | A hash of the identity provider's display configuration values. This hash contains `label`, `color`, `textcolor`, `icon`, `icon_type`, `display_name`, `provider_name`, and `documentation` parameters. | | | | `label` | *string* | The text label of the login button on the cPanel login interface. This value defaults to `_BUTTON_LABEL`. | A valid string. | `Log in to Izzy.` | | `color` | *string* | The background color of the button on the cPanel interface. This value defaults to `_BUTTON_COLOR` . | A valid RGB hexadecimal color value. | `cccccc` | | `textcolor` | *string* | The text color of the button on the cPanel interface. This value defaults to `_BUTTON_TEXT_COLOR`. | A valid RGB hexadecimal color value. | `000000` | | `icon` | *string* | The icon file to display in the button on the cPanel login interface. This value defaults to `_BUTTON_ICON` . If `_BUTTON_ICON` returns `0`, empty string, or `undef`, then the hash will not include this value. | A valid Base64-encoded image file. | | | `icon_type` | *string* | The icon file's MIME type. | A valid image format's MIME type. | `image/svg+xml` | | `display_name` | *string* | The identity provider's friendly name. This value defaults to `_DISPLAY_NAME`. | A valid string. | `Izzy` | | `provider_name` | *string* | The identity provider's system name. This value defaults to `_PROVIDER_NAME`. | A valid string. | `izzy` | | `documentation` | *string* | The public URL of the OpenID implementation's documentation at the openid.net website. | A valid publicly-available URL. | `https://developers.izzy.com/identity/protocols/OpenIDConnect` | | `_POSSIBLE_DISPLAY_USERNAME_KEY_NAMES` | *array* | An array that contains a list of keys in an attempt to get the display username from the `UserInfo` response.This value defaults to the email entry, and then uses the name entry if the email entry is not available.You may need to adjust this value in order to match the desired value for your identity provider.For more information, read OpenID's UserInfoResponse documentation. | An array of valid strings. | `email, name` | | `_POSSIBLE_DISPLAY_USERNAME_SUBKEY_NAMES` | *array* | An array that contains a list of sub keys in an attempt to get the display username from the `UserInfo` response.This value defaults to the `preferred` entry, and then uses the `account` entry if the `preferred` entry is not available.You may need to adjust this value in order to match the desired value for your identity provider.For more information, read OpenID's UserInfoResponse documentation. | An array of valid strings. | `preferred, account, business, personal` | | `_POSSIBLE_ID_TOKEN_KEY_NAMES` | *array* | An array that contains a list of ID Token keys in an attempt to get the ID token from the Token response.This value defaults to the `id_token` entry.You may need to adjust this value in order to match the desired value for your identity provider.For more information, read OpenID's TokenResponse documentation. | An array of valid strings. | `id_token` | | `_POSSIBLE_UNIQUE_IDENTIFIER_KEY_NAMES` | *array* | An array that contains a list of keys in an attempt to get the subject unique identifier from the access token response. This value defaults to the `email` entry, and then uses the `name` entry if the `email` entry is not available.You may need to adjust this value in order to match the desired value for your identity provider.For more information, read OpenID's TokenEndpoint documentation. | An array of valid strings. | `email, name` | | `_GET_SECRET_BASED_SIGNING_KEY_PLAINTEXT` | *string* | This method returns the secret that the system used to verify the signature of the ID tokens. This value defaults to the client's secret. | A valid string. | `Victoria` | | `_SCOPE` | *string* | This method allows you to declare an alternate or add an additional scope to the claim of your authorization request. This value defaults to `openid profile email`.For more information about scopes, read OpenID's scope documentation. | A valid string. | `openid profile email` | ## Example The following example uses the `Cpanel::Security::Authn::Provider::OpenIdConnectBase` base class and overrides the necessary methods to create an identity provider that connects to Google's authentication service: ``` package Cpanel::Security::Authn::Provider::Izzy; # cpanel - Cpanel/Security/Authn/Provider/Izzy.pm # Copyright(c) 2018 WebPros International, LLC # All rights Reserved. # copyright@cpanel.net http://cpanel.net # This code is subject to the cPanel license. Unauthorized copying is prohibited use strict; use parent 'Cpanel::Security::Authn::Provider::OpenIdConnectBase'; my $image = <