AzureGraph (version 1.0.1)

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.

• 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.

• config_file: Optionally, a JSON file containing any of the arguments listed above. Arguments supplied in this file take priority over those supplied on the command line. You can also use the output from the Azure CLI az ad sp create-for-rbac command.

• 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)

# }