azure_app_registration_guide.md

Create an Azure Active Directory App for OAuth2 Authentication

This step-by-step guide for creating an Azure Active Directory App will get the credentials needed to setup Microsoft OAuth2 Authentication in your Elixir / Phoenix App.

The guide follows the Official Microsoft Identity Platform docs. However we've added some details and screenshots to the steps to make it clear since navigating around Azure Portal can be confusing sometimes.

We check the instructions periodically as we know Azure changes their UI throughout time ... If anything has changed or you think some steps are missing, please open an issue.

1. Open Azure Portal

Assuming you already have a Microsoft account, you are eligible to use Azure Portal. You can use your account to try Azure Portal for free for 12 months. Don't worry, you won't have to pay anything as long as you don't use paid services after those 12 months elapse.

Microsoft has packages of paid services and free ones. The one we're using today - Active Directory - is free forever services.

Note: In typical Microsoft fashion, nothing is simple/straighforward ... "Azure Active Directory comes in four editions: Free, Office 365 apps, Premium P1, and Premium P2." azure.microsoft.com/en-us/pricing/details/active-directory ... The gist is this: if you have an Azure account, it's free. If you have Azuer "Premium" it's $6 user/month ... Don't worry, you can have an Elixir App that offers Microsoft OAuth for free. We checked. So you don't have to worry.

After you sign up / sign in, you are greeted with the Azure Portal webpage. Should look like this:

2. Go to Azure Active Directory

Now go to Azure Active Directory: https://portal.azure.com/?quickstart=true#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview

Note: this URL is likely to change as Microsoft Azure Product Managers have a habit of continuously "revising" things that were working fine. So your best bet might be to just search for: "Azure Active Directory"

You should see the following page. In the left pane, click on App Registrations.

Now click on App registration. This should prompt you to the next step.

3. Create your application

The "Register an application" form will be displayed.
Name your application whatever you want.
We called ours: "elixir-auth-microsoft-demo" for illustration.

On Supported account type, choose the one that is most appropriate to your situation.
If you're just trying out as a personal developer, choose the third option.

If you want to allow personal Hotmail/Outlook/XBox accounts, chose one that includes personal Microsoft accounts .

Note that if you select the first option you must also provide a custom authorize and token URLs:

export MICROSOFT_AUTHORIZE_URL=https://login.microsoftonline.com/<your_tenant_id>/oauth2/v2.0/authorize
export MICROSOFT_TOKEN_URL=https://login.microsoftonline.com/<your_tenant_id>/oauth2/v2.0/token

You can find <your_tenant_id> as "Directory (tenant) ID" on the app registration's overview page.

For the Redirect URI add http://localhost:4000 (the URI of your Phoenix application). You can edit this setting later on, so don't worry.

Once you click the Register button, you will see your newly created app:

Copy the Application (client) ID and save it in your editor for later.

4. Changing Settings

After registration, you should see several settings that you can tweak. The most relevant ones are Authentication and Certificates & Secrets.

4.1 - Changing Authentication URI

Let's start with Authentication. Click on the tab on the lefft-hand side panel:

We're going to click on the Add URI and add the callback path to our application. In our case: /auth/microsoft/callback This is the URI that Microsoft will redirect to after successful authentication.

e.g:

Click "Save" to save your changes.

4.2 - Adding Client Secret

We're using an auth code flow paired with Proof Key for Code Exchange (PKCE) and OpenID Connect (OIDC) https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow

That's a mouthfull of buzzwords, but don't worry, you don't need to understand any of it to get Auth working for your app. Just know that it's the current and most secure standard to get an access token and ID token.

We are using a client secret because we know this app will be hosted on a server and it's going to serve the files to the client, where environment variables are secured and not exposable (as is the case with web browsers).

To create a new secret, click on the the New client secret button:

Add a descriptive label and expiration time:

This will create a new secret. You want to copy the Value to use as the MICROSOFT_CLIENT_SECRET

Save two secrets to an .env file. e.g:

export MICROSOFT_CLIENT_SECRET=rDq8Q~.uc-237FryAt-lGu7G1sQkKR
export MICROSOFT_CLIENT_ID=a3d22eeb-85aa-4650-8ee8-3383931

Note: Don't worry, these aren't valid/real. They are just for illustration. Never share your keys/secrets! 🤐

The MICROSOFT_CLIENT_ID was visible at the end of step 3 as "Application (client) ID" on the Overview page.

5 - All Set! 🎉

At this point you can export these variables in your Phoenix app and everything should work.

Head back to the main README.md for the next steps.