From f5ea9f880a4ed8931f947f2fcefbe6c613733b1d Mon Sep 17 00:00:00 2001 From: Philippe Signoret Date: Sun, 20 Aug 2017 19:13:39 +0200 Subject: [PATCH] Update README to use new Azure portal --- README.md | 55 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 9a13dcc..56ffbea 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ A WordPress plugin that allows organizations to use their Azure Active Directory user accounts to sign in to WordPress. Organizations with Office 365 already have -Azure Active Directory and can use this plugin for all of their users. +Azure Active Directory (Azure AD) and can use this plugin for all of their users. - Azure AD group membership can be used to determine access and role. - New users can be registered on-the-fly based on their Azure AD profile. @@ -13,9 +13,9 @@ Azure Active Directory and can use this plugin for all of their users. In the typical flow: -1. User attempts to access the admin section of the blog (`wp-admin`). At the sign in page, they are given a link to sign in with their Azure Active Directory organization account (e.g. an Office 365 account). -2. After signing in, the user is redirected back to the blog with a JSON Web Token (JWT), containing a minimal set of claims. -3. The plugin uses these claims to attempt to find a WordPress user with an email address or login name that matches the Azure Active Directory user. +1. User attempts to log in to the blog (`wp-admin`). At the sign in page, they are given a link to sign in with their Azure Active Directory organization account (e.g. an Office 365 account). +2. After signing in, the user is redirected back to the blog with an authorization code, which the plugin exchanges for a ID Token, containing a minimal set of claims about the signed in user, and an Access Token, which can be used to query Azure AD for additional details. +3. The plugin uses the claims in the ID Token to attempt to find a WordPress user with an email address or login name that matches the Azure AD user. 4. If one is found, the user is authenticated in WordPress as that user. If one is not found, the WordPress user will (optionally) be auto-provisioned on-the-fly. 5. (Optional) Membership to certain groups in Azure AD can be mapped to roles in WordPress, and group membership can be used to restrict access. @@ -28,20 +28,43 @@ The following instructions will get you started. In this case, we will be config This plugin is not yet registered in the WordPress plugin directory (coming soon!), but you can still install it manually: 1. Download the plugin using `git` or with the 'Download ZIP' link on the right. -2. Place the `aad-sso-wordpress` folder in your WordPress' plugin folder. Normally, this is `/wp-content/plugins`. +2. Place the `aad-sso-wordpress` folder in your WordPress' plugin folder. Normally, this is `/wp-content/plugins`. 3. Activate the plugin in the WordPress admin console, under **Plugins** > **Installed Plugins**. ### 2. Register an Azure Active Directory application -For these steps, you must have an Azure subscription with access to the Azure Active Directory tenant that you would like to use with your blog. +With these steps, you will register an application with Azure AD. This application identifies your WordPress site with Azure AD. -1. Sign in to the [Azure portal](https://manage.windowsazure.com), and navigate to the **Active Directory** section. Choose the directory (tenant) that you would like to use. This should be the directory containing the users and (optionally) groups that will have access to your WordPress blog. -3. Under the **Applications** tab, click **Add** to register a new application. Choose 'Add an application my organization is developing', and a recognizable name. Choose values for sign-in URL and app ID URL. The blog's URL is usually a good choice. -4. When the app is created, under the **Configure** tab, generate a key (it will be visible once only, after you save).
IMPORTANT: This value is a secret! You should never share this with anyone. -5. Add a reply URL with the format: `https:///wp-login.php`, or whichever page your blog uses to sign in users. (Note: This page must invoke the `authenticate` action.) -6. Grant the application permission to call Azure AD Graph API. This is done by adding permissions to Windows Azure Active Directory, and checking Delegated Permission to "Enable sign-on and read users' profile" and "Read directory data". (The latter is currently only needed if Azure AD group to WordPress role mapping is used.) - ![Application permissions to Azure AD Graph API](https://cloud.githubusercontent.com/assets/231140/6990496/fcf02fb0-da21-11e4-9d60-1e6e2fd2cef1.png) -7. Save the application (and copy the secret key, which will appear after saving). +1. Sign in to the [**Azure portal**](https://portal.azure.com), and ensure you are signed in to the directory which has the users you'd like to allow to sign in. (This will typically be your organization's directory.) You can view which directory you're signed in to (and switch directories if needed) by clicking on your username in the upper right-hand corner. + +2. Navigate to the [**Azure Active Directory**](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade) blade, and enter the [**App registrations**](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) section. + + ![Clicking Azure Active Directory](https://user-images.githubusercontent.com/231140/29496874-6cf6f722-85dc-11e7-8898-89db80593ffc.png)
+ ![Clicking App registrations](https://user-images.githubusercontent.com/231140/29496884-9b3693ae-85dc-11e7-89a0-77e80979af23.png) + +3. Choose **New application registration**, and provide a name for your app. This will be the name displayed to users when signing in. Leave the default application type ("Web app / API"), provide the URL of your site as the "Sign-on URL", and click **Create**. When the app is created, select the newly-registered app from the list. + + ![Clicking New application registration](https://user-images.githubusercontent.com/231140/29496889-c5096a80-85dc-11e7-92e9-eafc49a2e0c6.png)
+ ![Creating new application](https://user-images.githubusercontent.com/231140/29496901-0d80184a-85dd-11e7-8121-7b0d6f2d5d48.png)
+ ![Selecting the newly-created app](https://user-images.githubusercontent.com/231140/29496910-38792bcc-85dd-11e7-9d01-7bded9a4090e.png) + +4. Under **Reply URLs**, update the existing reply URL with the format: `https:///wp-login.php`, or whichever page your blog uses to sign in users, and click **Save**. (Note: This page must invoke the `authenticate` action.) + + ![Adding a reply URL](https://user-images.githubusercontent.com/231140/29496951-54b63d74-85de-11e7-848d-d1ed0b7ce105.png) + +5. Under **Required permissions**, choose the "Windows Azure Active Directory" API. You will need at minimum delegated permissions to "Sign in and read user profile". If you wish to map Azure AD groups to WordPress roles, you will also need delegated permission to "Read all groups". Once you've selected the permissions, click **Save**. + + **Important**: The "Read all groups" delegated permissions requires a tenant administrator to consent to the application. The tenant administrator, can use the **Grant Permissions** option to grant permissions (i.e. consent) on behalf of all users. + + ![Delegated permissions to sign in and read all groups](https://user-images.githubusercontent.com/231140/29496967-cc635a78-85de-11e7-8e3c-34cc3ca39ac8.png) + +7. Under **Keys**, provide a new secret key description and duration, and click **Save**. After saving, the secret key value will appear. Copy it, as this is the only time it will be available. + + ![Creating a new secret key](https://user-images.githubusercontent.com/231140/29496984-395c4f36-85df-11e7-9c0c-0ecc912585f3.png) + +8. Keep a tab openwith the app registration page, as you will need to copy some fields when configuring the plugin. + + ![App settings summary page](https://user-images.githubusercontent.com/231140/29496998-8e1afd92-85df-11e7-96e7-0170b57939d1.png) ### 3. Configure the plugin @@ -55,17 +78,17 @@ Once the plugin is activated, update your settings from the WordPress admin cons
Client ID
- The application's client ID. (Copy this from the Azure AD application's configuration page.) + The Application ID. (Copy this from Azure AD application's configuration page.)
Client Secret
- The client secret key. (Copy this from the Azure AD application's configuration page.) + The secret key. (Copy this from the Azure AD application's configuration page.)
Reply URL
- The URL that Azure AD will send the user to after authenticating. This is usually the blog's sign-in page, which is the default value. + The URL that Azure AD will send the user to after authenticating. This is usually the blog's sign-in page, which is the default value. Ensure that the reply URL configured in Azure AD matches this value.