AzureGraph (version 1.0.3)

ms_graph: Azure Active Directory Graph

Description

Base class for interacting with Microsoft Graph API.

Usage

ms_graph

Format

An R6 object of class ms_graph.

Methods

• new(tenant, app, ...): Initialize a new Microsoft Graph connection with the given credentials. See 'Authentication' for more details.

• create_app(name, ..., password=NULL, password_duration=1, certificate=NULL, create_service_principal=TRUE): Creates a new registered app in Azure Active Directory. See 'App creation' below.

• get_app(app_id, object_id): Retrieves an existing registered app, via either its app ID or object ID.

• delete_app(app_id, object_id, confirm=TRUE): Deletes an existing registered app. Any associated service principal will also be deleted.

• create_service_principal(app_id, ...): Creates a service principal for a registered app.

• get_service_principal(): Retrieves an existing service principal.

• delete_service_principal(): Deletes an existing service principal.

• create_user(name, email, enabled=TRUE, ..., password=NULL, force_password_change=TRUE): Creates a new user account. By default this will be a work account (not social or local) in the current tenant, and will have a randomly generated password that must be changed at next login.

• get_user(user_id): Retrieves an existing user account.

• delete_user(user_id, confirm=TRUE): Deletes a user account.

• create_group(name, email, ...): Creates a new group. Note that only security groups can be created via the Microsoft Graph API.

• get_group(group_id): Retrieves an existing group.

• delete_group(group_id, confirm=TRUE): Deletes a group.

• call_graph_endpoint(op="", ...): Calls the Microsoft Graph API using this object's token and tenant as authentication arguments. See call_graph_endpoint.

Authentication

The recommended way to authenticate with Microsoft Graph is via the create_graph_login function, which creates a new instance of this class.

To authenticate with the ms_graph class directly, provide the following arguments to the new method:

• tenant: Your tenant ID. This can be a name ("myaadtenant"), a fully qualified domain name ("myaadtenant.onmicrosoft.com" or "mycompanyname.com"), or a GUID.

• app: The client/app ID to use to authenticate with Azure Active Directory. The default is to login interactively using the Azure CLI cross-platform app, but it's recommended to supply your own app credentials if possible.

• password: if auth_type == "client_credentials", the app secret; if auth_type == "resource_owner", your account password.

• username: if auth_type == "resource_owner", your username.

• certificate: If `auth_type == "client_credentials", a certificate to authenticate with. This is a more secure alternative to using an app secret.

• auth_type: The OAuth authentication method to use, one of "client_credentials", "authorization_code", "device_code" or "resource_owner". See get_azure_token for how the default method is chosen, along with some caveats.

• host: your Microsoft Graph host. Defaults to https://graph.microsoft.com/.

• aad_host: Azure Active Directory host for authentication. Defaults to https://login.microsoftonline.com/. Change this if you are using a government or private cloud.

• token: Optionally, an OAuth 2.0 token, of class AzureAuth::AzureToken. This allows you to reuse the authentication details for an existing session. If supplied, all other arguments will be ignored.

App creation

The create_app method creates a new registered app. By default, a new app will have a randomly generated strong password with duration of 1 year. To skip assigning a password, set the password argument to FALSE.

The certificate argument allows authenticating via a certificate instead of a password. This should be a character string containing the certificate public key (aka the CER file). Alternatively it can be an list, or an object of class AzureKeyVault::stored_cert representing a certificate stored in an Azure Key Vault. See the examples below.

A new app will also have a service principal created for it by default. To disable this, set create_service_principal=FALSE.

See Also

create_graph_login, get_graph_login

Microsoft Graph overview, REST API reference

Examples

# NOT RUN {
# start a new Graph session
gr <- ms_graph$new(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")

# authenticate with credentials in a file
gr <- ms_graph$new(config_file="creds.json")

# authenticate with device code
gr <- ms_graph$new(tenant="myaadtenant.onmicrosoft.com", app="app_id", auth_type="device_code")

# retrieve a registered app
gr$get_app(app_id="myappid")

# create a new app and associated service principal, set password duration to 10 years
app <- gr$create_app("mynewapp", password_duration=10)

# delete the app
gr$delete_app(app_id=app$properties$appId)
# ... but better to call the object's delete method directly
app$delete()

# create an app with authentication via a certificate
cert <- readLines("mycert.cer")
gr$create_app("mycertapp", password=FALSE, certificate=cert)

# }