A note on the Microsoft Graph (Office365) API for obtaining and using an admin token.
impetus
I tried to add and remove users and groups in Azure Active Directory using the API.
The Azure Active Directory API has been integrated with the Microsoft Graph (Office365) API and will use the Microsoft Graph API.
Explanation of Microsoft Graph API
I found a lot of documents when I looked into it, and it was quite confusing, so I'll try to summarize it in a nutshell.
What is Microsoft Graph (Office365) API?
Microsoft Graph (Office365) API is an API that allows you to manipulate Office365.
You can send and receive Outlook email, edit Excel online Excel files, and perform a variety of other Office365 operations in the cloud.
Office365 users and groups can also operate with Azure Active Directory, as mentioned above.
In this case, it was used for Azure Active Directory operation purposes.
With/without user, delegation/application differences
The Graph API documentation shows that the token has a
- Obtain access on behalf of the user
- Get access without a user
- Delegated access permissions
- Application Permissions
I was confused by the multiple names, such as
There are many ways to call it, but the bottom line is to think about whose Office365 can be manipulated by the API.
Obtain access on behalf of the user
This is a token that is often seen in Google and Facebook authentication, etc. When you click on the link, a login page opens, and when you log in, an agreement screen appears.... This is a token that is obtained in this way.
A token is issued that allows you to log in and operate Office365 for those who have agreed to do so.
So, when you use that token to retrieve email, the email you can retrieve will be the email that was delivered to the inbox of the person who agreed to it.
In other words, it is a token that takes the place of the person who has agreed to it, and is therefore referred to as "gaining access on behalf of the user" or Delegated access permissions" because it is a token on behalf of the person who has agreed to it.
Get access without a user
At first, I was confused because I thought "no user" meant no user for all APIs. I was confused because I thought that "no user" meant that there was no target user, i.e., access with "administrative privileges" without going through the user consent flow.
In summary, the Graph API can be divided into two main categories: "operation with agreed user authority" and "operation without target user and with administrator authority.
In this case, we wanted to manage Azure Active Directory users and groups, so we will obtain and use a token for administrative privileges.
If the user was an administrator, with user consent, he or she can obtain a token that allows him or her to operate not only his or her Office365, but also to operate with administrative privileges.
However, since obtaining tokens by user consent is complicated, and since this was for administrative work from the program, we decided to obtain tokens by "operation with administrator authority, without target users" this time.
Below are the instructions for obtaining and using the Microsoft Graph (Office365) API tokens with no target user and with administrative privileges.
procedure
I proceeded with reference to Official Documents."
I have described the procedure here with explanations focusing on the points I got stuck on.
App Registration
Regardless of whether you have user or administrator privileges, you must first register your app with Azure Active Directory.
The procedure for this area is described in the following article on the previous acquisition of user authority tokens.
The following procedure is for settings within each application registered in Azure Active Directory.
Adding API permissions
The Graph API can perform a variety of operations, but you set what operations you want it to be able to perform.
[API Permissions]-[+Add Permissions]
Various APIs are available, but here we select "Microsoft Graph".
Next you will see "Delegated Permissions" and "Application Permissions".
In fact, this is what the aforementioned With User or Without User is all about. Without? and select "Allow applications" without users.
You will then see a list of scopes that require administrative privileges, which you can select.
For example, to get the Azure Active Directory group, select [Group]-[Group.Read.All].
API Administrator Consent
Just adding the scope of "Administrative Authority" is not enough to use it yet; the administrator's consent is required.
For administrator consent, click below in the administrator account.
[Active[API permissions]-[give administrative consent to xxxx].
Client Secret Issued
Tokens for administrative privileges can be obtained by issuing a client secret in advance and accessing the specified URL with that client secret.
The client secret is issued by
[Certificates and Secrets]-[+New Client Secret]
Token acquisition
When information about the application is sent via POST to the URL to obtain a token, a token is returned as a response.
Note the information about the following apps from Azure Active Directory.
tenant ID
[Summary]-[Application (Client) ID].
application ID
[Summary]-[Application (Client) ID].
client secret
- as above
The URL to obtain the token is listed below.
[Quick Start]-[Endpoints View]-[OAuth2.0 Token Endpoints (v2)
The acquisition of the administrator token is as follows
import axios from 'axios'; const querystring: any = require('querystring'); const TENANT_ID = 'xxxx' const CLIENT_ID = 'xxxx'; const CLIENT_SECRET = 'xxxx'; (async () => { const qs = querystring.stringify({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, scope: 'https://graph.microsoft.com/.default', grant_type: 'client_credentials' }); const url = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`; const result = await axios.request({ url, method: "POST", data: qs }); const access_token = result.data.access_token; console.log(access_token); })();
Token Use
The Graph API is then called using the token obtained.
The Graph API documentation is available at this way (direction close to the speaker or towards the speaker).
There are many things that are not clear from the documentation alone, and I think it is a good idea to actually try things out.
For example, a list of groups in Azure Active Directory can be obtained at
import axios from 'axios'; const ACCESS_TOKEN = 'xxxx'; (async () => { const itemList = []; const url = 'https://graph.microsoft.com/v1.0/groups'; let page = url; do { const result = await axios.request({ headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` }, url: page, method: "GET" }); itemList.push(...result.data.value); page = result.data["@odata.nextLink"]; } while (page); console.log(itemList); })();
Impressions, etc.
There are two types of APIs for Azure Active Directory, "Azure Active Directory Graph" and "Microsoft Graph", and two types of Microsoft Graph APIs, "v1" and "v2" for obtaining access tokens.
It took me a long time to sort through the information and get an overview because when I searched, all of this information came in a jumble and at the same time.
Active Directory and Office, previously closed on-premises, are now configured in the cloud in the form of Azure Active Direcotyr and Office365.
User IDs will also be unique across both corporate users (Azure Active Directory) and individual users (Microsoft account) with the base platform integrated across both.
Office365 users and groups are configured in Azure Active Directory, and Office365 and Azure Active Directory are also integrated.
When was that grand integration of those things done? That's amazing.
Multiple APIs and endpoints were introduced during the transitional period of integration, and the remnants of these APIs and endpoints remain, but from this integration flow, the acquisition of access tokens will be unified with the "v2" endpoint, regardless of corporate or individual users, and the API will be "Microsoft Graph" to do anything The API will be "Microsoft Graph" so that anything can be done. This is likely to be the mainstream in the future.
So, let's integrate Azure, which is doing very well! I guess that's what it's going to come down to.
