cordova-plugin-ms-aad-graph

Apache Cordova plugin for Microsoft Azure Active Directory Graph

Provides JavaScript API to work with Microsoft Azure Active Directory Graph. ####Supported Platforms####

• Android (cordova-android@>=4.0.0 is supported)
• iOS
• Windows (Windows 8.0, Windows 8.1 and Windows Phone 8.1)

Sample usage

To access the AAD Graph API you need to acquire an access token and get the AAD client. Then, you can send async queries to interact with AAD entities. Note: application ID, authorization and redirect URIs are assigned when you register your app with Microsoft Azure Active Directory.

var resourceUrl = 'https://graph.windows.net/';
var tenantName = 'sampleDirectory2015.onmicrosoft.com';
var endpointUrl = resourceUrl + tenantName;
var appId = '98ba0820-f7da-4411-87bb-598e0475536b';
var authority = 'https://login.windows.net/' + tenantName + '/';
var redirectUrl = 'http://localhost:4400/services/aad/redirectTarget.html';

var AuthenticationContext = Microsoft.ADAL.AuthenticationContext;
var ActiveDirectoryClient = Microsoft.AADGraph.ActiveDirectoryClient;

var authContext = new AuthenticationContext(authority);
var client = new ActiveDirectoryClient(endpointUrl, authContext, resourceUrl, appId, redirectUrl);

client.users.getUsers().fetchAll().then(function (users) {
    result.forEach(function (user) {
        console.log('User: ' + user.displayName + ' PrincipalName: ' + user.userPrincipalName);
    });
}, function(error) {
    console.log(error);
});

Complete example is available here.

Installation Instructions

Use Apache Cordova CLI to create your app and add the plugin.

1. Make sure an up-to-date version of Node.js is installed, then type the following command to install the Cordova CLI:

    npm install -g cordova
   

2. Create a project and add the platforms you want to support:

    cordova create aadClientApp
    cd aadClientApp
    cordova platform add windows <- support of Windows 8.0, Windows 8.1 and Windows Phone 8.1
    cordova platform add android
    cordova platform add ios
   

3. Add the plugin to your project:

    cordova plugin add https://github.com/AzureAD/azure-activedirectory-cordova-plugin-graph
   

4. Build and run, for example:

    cordova run android
   

To learn more, read Apache Cordova CLI Usage Guide.

Common operations

Getting entities

// Option #1: client.<entities>.get<Entities>().fetchAll().then(win, fail);
client.users.getUsers().fetchAll().then(function(itemsArray) { 
    ... 
}, function(err) { 
    ... 
});

// Option #2: client.directoryObjects.as<Entities>().getDirectoryObjects().fetchAll().then(win, fail);
client.directoryObjects.asApplications().getDirectoryObjects().fetchAll().then(function(itemsArray) { 
    ...
}, function(err) { 
    ... 
});

// Get by objectId: client.<entities>.get<Entity>(objectId).fetch().then(win, fail);
client.devices.getDevice('33f8f7d8-38e4-44f8-acf3-2745cb6d2e80').fetch().then(function(device) { 
    ... 
}, function(err) { 
    ... 
});

// Or alternatively:
client.directoryObjects.asUsers().getDirectoryObject('33f8f7d8-38e4-44f8-acf3-2745cb6d2e80').fetch().then(function(user) { 
    ... 
}, function(err) { 
    ... 
});

Adding entities

// Option #1: client.<entities>.add<Entity>(instance).then(win, fail);
client.users.addUser(user).then(function(addedUser) { 
    ... 
}, function(err) { 
    ... 
});

// Option #2: client.directoryObjects.as<Entities>().addDirectoryObject(instance).then(win, fail);
client.directoryObjects.asGroups().addDirectoryObject(group).then(function(addedGroup) { 
    ... 
}, function(err) { 
    ... 
});

Updating entities

client.groups.getGroup(objectId).fetch().then(function (groupFoundById) {
    groupFoundById.displayName = 'Updated group name';
    groupFoundById.update().then(function () { ... }, function (err) { ... });
}, function (err) { ... });

Deleting entities

client.groups.getGroup(objectId).fetch().then(function (groupFoundById) {    
    groupFoundById.delete().then(function () { ... }, function (err) { ... });
}, function (err) { ... });

Queries, Filters and Paging

filter

client.users.getUsers().filter("displayName eq 'John Trident'").fetchAll().then( ... );
client.users.getUsers().filter("startswith(displayName,'test')").fetchAll().then( ... );

top

client.users.getUsers().top(3).fetchAll().then( ... )

orderBy

client.users.getUsers().orderBy('displayName').fetchAll().then( ... )

Combinations

client.users.getUsers().top(3).orderBy('displayName').fetchAll().then( ... )

Note: combining of filter and orderBy is not supported.

paging

Results are being paginated when fetch method is used:

client.users.getUsers().fetch().then(function(pagedCollection) { 
    pagedCollection.currentPage.forEach(function (user) {
        console.log('User "' + user.displayName + '" userPrincipalName: "' + user.userPrincipalName + '"');
    });

    pagedCollection.getNextPage().then(function(secondPagedCollection) {
        ...
    }, function(err) { 
        ... 
    });
}, function(err) { 
    ... 
});

Notes:

• Queries are not yet supported along with fetch by AAD Graph JS SDK,
• getPreviousPage is not yet supported by AAD Graph JS SDK.

Entity types and their specific operations

Users

Creating and initializing an entity instance

var user = new AadGraph.User();
user.displayName = 'displayName';
user.mailNickname = 'mailNickname';
user.userPrincipalName = displayName + '@' + tenantName;
var passwordProfile = new AadGraph.PasswordProfile();
passwordProfile.password = "tempPassword1234";
passwordProfile.forceChangePasswordNextLogin = true;
user.passwordProfile = passwordProfile;
// `usageLocation` property is required in order to use `assignLicense` method (see example below):
user.usageLocation = 'US';
user.accountEnabled = true;

Managing subscriptions and plans

You can call on user assignLicense to add or remove subscriptions for the user. You can also enable and disable specific plans associated with a subscription.

Adding a subscription with its service plans:

user.assignLicense([
{
    "disabledPlans": [],
    "skuId": subscribedSkuId
}], []).then(function () { ... }, function(err));

Disabling subscription plan:

user.assignLicense([
{
    "disabledPlans": [servicePlanIdToDisable],
    "skuId": subscribedSkuId
}], []).then(function () { ... }, function(err));

Removing subscription:

user.assignLicense([], [subscribedSkuIdToRemove]);

Reseting user password

To reset user password you should update its PasswordProfile property. For example:

user.passwordProfile = new AadGraph.PasswordProfile();
user.passwordProfile.password = "ChangedPass1234";
user.passwordProfile.forceChangePasswordNextLogin = true;
user.update().then( ... );

Manager

// Getting
user.manager.fetch().then(function(manager) { ... }, function(err) { ... });

// Updating
user.update_manager(anotherUser).then(function () { ... }, function(err) { ... });

DirectReports

The Get User’s Direct Reports operation returns a list of the user’s direct reports. These are users and contacts that have their manager navigation property set to the user on which the operation is performed.

user.directReports.getDirectoryObjects().fetchAll().then(function(reports) { 
    ...
}, function(err) { 
    ...
});

memberOf

user.memberOf.getDirectoryObjects().fetchAll().then( ... )

OAuth2PermissionGrants

user.oauth2PermissionGrants.getOAuth2PermissionGrants().fetchAll().then( ... );

AppRoleAssignments

user.appRoleAssignments.getAppRoleAssignments().fetchAll().then( ... )

user.appRoleAssignments.addAppRoleAssignment(newItem).then(function(addedItem) { 
    ... 
}, function(err) { 
    ... 
});

Groups

Creating and initializing an entity instance

var group = new AadGraph.Group(client.context);
group.displayName = 'myGroup';
group.mailNickname = 'groupMailNickName';
group.mailEnabled = 'false';
group.securityEnabled = 'true';`

Members

group.members.getDirectoryObjects().fetchAll().then(function(members) { 
    ... 
}, function(err) { 
    ... 
});

group.addMember(newMember).then(function () { 
    ... 
}, function(err) { 
    ... 
});

group.deleteMember(existingMember).then(function () { 
    ... 
}, function(err) { 
    ... 
});

Note: members property is applicable to DirectoryRole as well.

isMemberOf

client.isMemberOf(group.objectId, user.objectId).then(function(obj) {
   if (obj.value === true) { console.log('the member is in the group'); } 
}, function(err) { ... });

getMemberGroups

Call the getMemberGroups function on a user, contact, group, or service principal to get the group objectId's that it is a member of. You can pass boolean argument to get only security enabled groups.
For example,

// `securityEnabledOnly` - false by default
user.getMemberGroups().then(function (groupIds) {}, function(err) { ... });

// `securityEnabledOnly` = true
user.getMemberGroups(true).then(function (groupIds) {}, function(err) { ... });

getMemberObjects

This function is similar to getMemberGroups but it returns role objectIds as well.

checkMemberGroups

You can call checkMemberGroups on an instance to check its membership in a list of groups.

user.checkMemberGroups([group1.objectId, group2.objectId]).then(function (groupIds) {
    // groupIds is an array containing parent groups objectId's
}, function (err) { 
    ... 
});

Applications

Creating and initializing an entity instance

var app = new AadGraph.Application(client.context);
var identifierUrl = 'https://contoso.com/app';
app.displayName = 'MyApp';
app.identifierUris = [identifierUrl];

Getting deleted applications

client.deletedDirectoryObjects.asApplications().fetchAll().then(function(apps) { ... }, function(err) { ... })

Restoring deleted applications

identifierUris argument can be passed to restore method if you need to update the old value.

For example:

client.deletedDirectoryObjects.asApplications().fetchAll().then(function (apps) {
    apps[0].restore().then(function (restoredApp) {
        apps[1].restore(['https://contoso.com/app']).then(function (secondRestoredApp) { 
            ... 
        }, function(err) { ... });
    }, function(err) { ... });
}, function(err) { ... });

Directory Schema Extensions

Creating and initializing an entity instance

var property = new AadGraph.ExtensionProperty();
property.name = 'skypeId';
property.dataType = 'String';
property.targetObjects = property.targetObjects.concat('User');

Adding an extension

client.applications.addApplication(that.createApp()).then(function (app) {
    app.extensionProperties.addExtensionProperty(extensionRaw).then(function (extension) {
        // The name should become a fully-qualified extension property name like 'extension_ab603c56068041afb2f6832e2a17e237_skypeId'
        console.log(extension.name);
        ...
    });
});

Writing and reading an extension property

...
user['extension_ab603c56068041afb2f6832e2a17e237_skypeId'] = 'live:userSkypeId';
user.update().then(function() {
    client.users.getUser(user.objectId).fetch().then(function (updatedUser) {
        console.log(updatedUser['extension_ab603c56068041afb2f6832e2a17e237_skypeId']);
    });
});

Note: extension properties reading and writing are not currently supported by JS SDK.

Creating and initializing other entity types

Creating a service principal for an app

var principal = new AadGraph.ServicePrincipal();
principal.appId = app.appId;

Creating an oauth2PermissionGrant

var grant = new AadGraph.OAuth2PermissionGrant(client.context);
grant.resourceId = resourceId;
grant.clientId = clientId;
grant.principalId = principalId;
grant.consentType = 'Principal';
grant.startTime = '2014-03-01';
grant.expiryTime = '2014-04-01';

Creating a device

var device = new AadGraph.Device();
device.displayName = 'myDevice';
device.deviceId = deviceId;
device.accountEnabled = true;
var altSecId = new AadGraph.AlternativeSecurityId();
altSecId.key = btoa(key);
altSecId.type = type;
// Triggering _identityProviderChanged to become true as this field is required in request
altSecId.identityProvider = null;
device.alternativeSecurityIds = [altSecId];
device.deviceOSType = OSType;
device.deviceOSVersion = OSVersion;

Creating an appRoleAssignment

var assignment = new AadGraph.AppRoleAssignment();
assignment.id = id;
assignment.resourceId = resourceId;
assignment.principalId = principalId;

Copyrights

Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use these files except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.