銷售: 1-800-867-1380

Adding, Updating, and Removing an App

更新日期: 2013年6月

This topic shows you how to add, update, or remove an app in Windows Azure AD. You can view all of your existing integrated apps in the Windows Azure Management Portal by clicking on your directory tenant, then clicking Applications. For more information about app properties, see Application Objects and Service Principal Objects.

Adding an App

An app must be registered with Windows Azure AD to integrate it with your directory tenant. During registration, you can choose what kind of integration the application needs. All integrated applications are enabled for single sign-on, but you can choose whether you want read or read/write access to directory data.

If you want to make your application available to other organizations, you will also need to enable external access once the application has been added.

To add an Integrated App in the Windows Azure Management Portal

  1. Click on the Active Directory icon on the left menu, then click on the directory tenant you want to add an app to.

  2. On the top menu, click Applications. If no apps have been added to your directory tenant, this page will only show the Add an App link. Click on the link, or alternatively you can click on the Add button on the command bar.

  3. On the Tell us about your app page, you must specify a name for your app as well as indicate the type of access that your app needs to Windows Azure AD. These selections can always be changed later. Once you have made your selections, click the arrow icon on the bottom-right corner of the page.

  4. On the App properties page, provide the App URL and App ID URI for your application, then click the checkbox in the bottom-right hand corner of the page.

  5. You are redirected to the Quick Start page for your application. You can now begin updating your application to enable single sign-on, read or write directory data, or enable access by other organizations.

    note附註
    If you try to log in to an application immediately after adding it to Windows Azure AD, the log-in attempt might fail with error ACS50042. Wait a few minutes and try to log in again. For more information, see ACS Error Codes.

Native Client Applications (Preview)

Windows Azure AD now has developer preview support for registering a native client application. A native client is an application that is installed on a device such as a phone or computer. Native client applications can be integrated with Windows Azure AD to access web APIs on behalf of a user in a Windows Azure AD directory.

This functionality is described in the following example scenario: a developer has created a native client application that needs to call a web API. The web API is secured by Windows Azure AD, which uses OAuth 2.0 to allow authenticated users and authorized applications to call it. To enable this scenario, both applications (the native client application and the web API) are registered in Windows Azure AD, and the native client application is configured with permissions to call the web API on behalf of an authenticated user. Now the native client application is able to access the web API on behalf of an authenticated user of the application, and calls made to the downstream web API are authorized with the user’s credentials.

More information about how to enable this scenario will be available soon.

Application Access Levels

The three access levels for integrated applications are listed in the table below:

 

Access Level Type Description

Single Sign-On

Default permission. The app is enabled for single sign-on with Azure AD, and the user token will contain claims such as the user’s User Principal Name, First and Last Name and unique identifiers.

Single Sign-On, Read Directory Data

Single sign-on plus the ability to read directory data using the Graph API. This allows querying of company, user and group information.

Single Sign-On, Read and Write Directory Data

Single sign-on plus the ability to read and write directory data using the Graph API. This allows querying and writing of company, user, and group information, but does not allow deleting users or groups.

Updating an App

There are many reasons why you may want to update an app you have already integrated with Windows Azure AD. For example, if you are developing an initial prototype or staging your app for the first time, you may have configured it with properties that you want to change when it’s moved to a production environment. You will also need to update your app if you want to allow access for users in other organizations, add keys to access the Graph API, change the location where your app is hosted, and more.

Enabling External Users to Grant Access

If you are writing an app that you want to make available to your customers or partners outside of your organization, you will need to update the app definition in the Windows Azure Management Portal.

note附註
When enabling external access, you must ensure that your application’s APP ID URI belongs in a verified domain. Additionally, the Return URL must begin with https://. For more information, see Application Objects and Service Principal Objects.

To enable access to your app for external users

  1. In the Windows Azure Management Portal, click on your directory tenant, click Applications from the top menu, then click the app you want to configure. The Quick Start page will appear with single sign-on and other configuration information.

  2. Expand the Enable your app for external users section of the Quick Start, then click the Configure external access link in the Enable Access section. The application properties page will appear.

  3. Click the On button next to External Access, then click the Save button on the command bar.

Once you have made the change above, company administrators in other organizations will be able to grant your app access to their directory data.

Building the Link that Grants Access for External Users

In order for external users to sign up for your app using their organizational accounts, you’ll need to update your app to show a button that links to the page on Windows Azure AD that enables them to grant access. Branding guidance for this sign up button is discussed in the Branding Guidelines for Integrated Apps topic. After the user either grants or denies access, the Windows Azure AD grant access page will redirect the browser back to your app with a response. For more information about application properties, see Application Object.

The grant access page is created by Windows Azure AD, and you can find a link to it in your app’s Configuration page in the Management Portal. To get to the Configuration page, click on the Applications link in the top menu of your Windows Azure AD tenant, click the app you want to configure, then click on Configure from the top menu of the Quick Start page.

The link for your application will look like this: http://account.activedirectory.windowsazure.com/Consent.aspx?ClientID=058eb9b2-4f49-4850-9b78-469e3176e247&RequestedPermissions=DirectoryReaders&ConsentReturnURL= https%3A%2F%2Fadatum.com%2FExpenseReport.aspx%3FContextId%3D123456. The following table describes the parts of the link:

 

Parameter Description

ClientId

Required. The Client ID you obtained as part of adding your app.

RequestedPermissions

Optional. Access level that your app is requesting, that will be displayed to the user granting your app access. If not specified, the requested access level will default to single sign-on only. The other options are DirectoryReaders and DirectoryWriters. See Application Access Levels for more details on these access levels.

ConsentReturnUrl

Optional. The URL that you want the grant access response returned to. This value must be URL-encoded and must be under the same domain as the Reply URL configured in your app definition. If not supplied, the grant access response will be redirected to your configured Reply URL.

Specifying a ConsentReturnUrl separate from the Reply URL will allow your app to implement separate logic that can process the response on a different URL from the Reply URL (which normally processes SAML tokens for sign on). You may also specify additional parameters in the ConsentReturnURL encoded URL; these will be passed back as query string parameters to your app upon redirection.  This mechanism can be used to maintain additional info or to tie your app’s request for an access grant to the response from Azure AD.

Grant Access User Experience and Response

When an application redirects to the grant access link, the following images demonstrate what the user will experience.

If the user is not already signed in, they will be prompted to do so:

登入 AAD

Once the user is authenticated, Windows Azure AD will redirect the user to the grant access page:

授與存取權

note附註
Only the company administrator of the external organization can grant access to your app. If the user is not a company administrator, they will be given the option to send mail to their company administrator to request that this app be granted access.

After the customer has granted access for your app by clicking Grant Access, or if they have denied access by clicking Cancel, Windows Azure AD sends a response to the ConsentReturnUrl or to your configured Reply URL. This response contains the following parameters:

 

Parameter Description

TenantId

The unique ID of the organization in Windows Azure AD that has granted access for your app. This parameter will only be specified if the customer granted access.

Consent

The value will be set to Granted if the app was granted access, or Denied if the request was rejected.

Additional parameters will be returned to the app if they were specified as part of the ConsentReturnUrl encoded URL. The following is an example response to a grant access request that indicates the application has been authorized, and it includes a ContextID that was supplied in the grant access request: https://adatum.com/ExpenseReport.aspx?ContextID=123456&Consent=Granted&TenantId=f03dcba3-d693-47ad-9983-011650e64134

note附註
The access grant response will not contain a security token for the user; the app must sign the user in separately.

The following is an example response to an access grant request that was denied: https://adatum.com/ExpenseReport.aspx?ContextID=123456&Consent=Denied

Rolling App Keys for Uninterrupted Access to the Graph API

During the lifetime of your app, you may need to change the keys that you use when you call into Windows Azure AD to acquire an access token to call the Graph API. Generally changing keys falls into two categories: emergency roll over where your key has been compromised or a roll over when your current key is about to expire. The following procedure should be followed to provide your app with uninterrupted access while you refresh your keys (primarily for the second case).

  1. In the Windows Azure Management Portal, click on your directory tenant, click Applications from the top menu, then click the app you want to configure. The Quick Start page will appear with single sign-on and other configuration information.

  2. Click on Configure in the top menu to see a list of your app’s properties, and you’ll see a list of your keys.

  3. Under Keys, click on the drop down that says Select duration and pick 1 or 2 years, and then click Save in the command bar. This generates a new password key for your app. Copy this new password key. At this point both the existing and new key can be used by your app to obtain an access token from Windows Azure AD.

  4. Go back to your app and update the configuration to start using the new password key. See Using the Graph API to Query Windows Azure AD for an example of where this update should happen.

  5. You should now roll this change out across your production environment – verifying it first on one service node, before rolling it out across the rest.

  6. Once the update is complete across your production deployment, you are free to come back to the Windows Azure Management Portal and remove the old key.

Changing App Properties After Enabling Access

Once you enable access for external users to your app, you may still continue to make changes to your app’s properties in the Azure Management Portal. However, customers who have already granted access to your app before you made app changes will not see those changes reflected when viewing details about your app in the Azure Management Portal. Once the app is made available to customers, you need to be very careful when making certain changes. For example, if you update the App ID URI, then your existing customers who granted access before this change will be unable to log in to your app using their company or school accounts.

If you make a change to the RequestedPermissions to request a greater access level, existing customers using app functionality that now leverages new API calls using this increased access level may get an access denied response from the Graph API. Your app should handle these cases and ask the customer to grant access to your app with the request for an increased access level.

Removing an App

Removing or deleting an app definition from your directory tenant is currently not available.

note附註
If an app definition that you want to delete is using an App ID URI that you want to reuse in a different app definition, you can change the existing app definition’s App ID URI to make it available for use in your new app definition.

During development, in your own directory tenant, you can set three different app access levels, as well as completely removing app access to your directory tenant.

If your app is made available to your customers, then once your customer (a company administrator for his/her directory) has granted access, they may decide that they wish to remove access for your app (also known as revocation). The company admin can do this from the Windows Azure Management Portal. Removing access does not delete any customer data from the directory or from your app – it merely removes your app’s access to the customer directory.

note附註
In order for a company administrator to remove an app’s access to their directory (after having granted consent), the company administrator must have an Azure subscription to remove access through the Windows Azure Management Portal. Alternatively, the company administrator can use Windows Azure AD PowerShell Cmdlets to remove access.

本文對您有任何幫助嗎?
(剩餘 1500 個字元)
感謝您提供意見
顯示:
© 2014 Microsoft