• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

AzureAD/azure-activedirectory-library-for-android: The ADAL SDK for Android give ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

AzureAD/azure-activedirectory-library-for-android

开源软件地址(OpenSource Url):

https://github.com/AzureAD/azure-activedirectory-library-for-android

开源编程语言(OpenSource Language):

Java 99.5%

开源软件介绍(OpenSource Introduction):


This library, ADAL for Android, will no longer receive new feature improvements. Instead, use the new library MSAL for Android.

  • If you are starting a new project, you can get started with the MSAL for Android docs for details about the scenarios, usage, and relevant concepts.
  • If your application is using the previous ADAL for Android library, you can follow this migration guide to update to MSAL for Android.
  • Existing applications relying on ADAL for Android will continue to work.

Documentation Code Samples Developer Guide Feedback

Microsoft Azure Active Directory Authentication Library (ADAL) for Android

ADAL for Android gives you the ability to add support for Work Accounts to your application. This SDK gives your application the full functionality of Microsoft Azure AD, including industry standard protocol support for OAuth2, Web API integration with user level consent, and two-factor authentication support. Best of all, it’s FOSS (Free and Open Source Software) so that you can participate in the development process as we build these libraries.

A Work Account is an identity you use to get work done from your organization or school. Anywhere you need to get access to your work life you'll use a Work Account. The Work Account can be tied to an Active Directory server running in your datacenter or live completely in the cloud like when you use Office 365. A Work Account will be how your users know that they are accessing their important documents and data backed my Microsoft security.

ADAL for Android 3.0.0 Released!

Please note: Production ADAL 2.0.x releases (first released March 2020) are neither API-compatible nor cache-compatible with the following versions:
    - 2.0-alpha (released 2015-07-27)
    - 2.0.1-alpha (released 2015-09-25)
    - 2.0.2-alpha (released 2016-05-27)
    - 2.0.3-alpha (released 2016-06-11)
    - 2.0.4-alpha (released 2017-02-17)

Build status

Branch Status
dev (Travis) Build Status
dev (VSTS) Build status

Note: A corpnet account is required to view the VSTS build.

Versions

Current version - 3.1.2

Minimum recommended version - 1.16.3-hf1

You can find version-to-version differences in the change log.

Features

  • Industry standard Oauth2 protocol support.
  • Id Token exposure for full access to the token contents.
  • Multi-resource refresh token allows for apps registered together to access different APIs without prompting the user.
  • Cache with Encryption for easily accessing existing tokens and session state with assurance it wasn't tampered with.
  • Support for the Microsoft Azure AD Authenticator plug-in for Android, which will be released soon!
  • Dialog and Fragment support

Samples and Documentation

We provide a full suite of sample applications and documentation on GitHub to help you get started with learning the Azure Identity system. This includes tutorials for native clients such as Windows, Windows Phone, iOS, OSX, Android, and Linux. We also provide full walkthroughs for auth flows, the Microsoft Graph API, other Microsoft APIs, and other Azure AD features.

Checkout the ADAL for Android sample app for help getting started.

Looking for Xamarin?

Community Help and Support

We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browse existing issues to see if someone has had your question before.

Submit Feedback

We'd like your thoughts on this library. Please complete this short survey.

SSO and Conditional Access Support

This library allows your application to support our Enterprise Mobility Suite, including Conditional Access, so businesses can use your application in their secure environment.

To configure your application to support these scenarios, please read this document: How to enable cross-app SSO on Android using ADAL

Security Reporting

If you find a security issue with our libraries or services please report it to [email protected] with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

Contributing

All code is licensed under the MIT license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback.

For more details about contribution

Quick Start

To build with Gradle,

  • Clone this repo in to a directory of your choice
  • Setup emulator with SDK 23
  • Go to the root folder where you cloned this repo
  • To run the sample app, connect the test device and run the command: ./gradlew :userappwithbroker:installDebug
  • You should see app 'Fancy ADAL Test App' installed on the test device
  • Select an authority, [optionally] enter a login hint and/or query parameters, and click Acquire Token to enter credentials with AAD

Note: The authority, clientId, redirectUri and resource of the test app can be found in Constants.java. These values can be updated as necessary to test different tenants and configurations.

To build with Maven, you can use the pom.xml at top level

  • Clone this repo in to a directory of your choice
  • Follow the steps at Prerequisites section to setup your maven for android
  • Setup emulator with SDK 19
  • Go to the root folder where you cloned this repo
  • Run the command: mvn clean install
  • Change the directory to the Quick Start sample: cd userappwithbroker/
  • Run the command: mvn android:deploy android:run
  • You should see app launching
  • Enter test user credentials to try!

Jar packages will be also submitted beside the aar package.

Download

We've made it easy for you to have multiple options to use this library in your Android project:

  • You can use the source code to import this library into Android Studio and link to your application.
  • If using Android Studio, you can use aar package format and reference the binaries.

Option 1: Source via Git

To get the source code of the SDK via git:

git clone --recurse-submodules [email protected]:AzureAD/azure-activedirectory-library-for-android.git
cd ./azure-activedirectory-library-for-android/src

Option 2: Binaries via Gradle

You can get the binaries from Maven central repo. AAR package can be included as follows in your project in AndroidStudio:

repositories {
    mavenCentral()
    maven {
        // Surface Duo SDK dependency.
        url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed%40Local/maven/v1'
    }
}
dependencies {
    // your dependencies here...
    compile('com.microsoft.aad:adal:3.0.1') {
        // if your app includes android support
        // libraries, Gson or Surface Duo SDK 
        // in its dependencies, exclude that 
        // groupId from ADAL's compile task by 
        // un-commenting the appropriate line below

        // exclude group: 'com.android.support'
        // exclude group: 'com.google.code.gson'
        // exclude group: 'com.microsoft.device.display'
    }
}

Option 3: aar via Maven

If you are using the m2e plugin in Eclipse, you can specify the dependency in your pom.xml file:

<dependency>
    <groupId>com.microsoft.aad</groupId>
    <artifactId>adal</artifactId>
    <version>3.0.1</version>
    <type>aar</type>
</dependency>

Option 4: jar package inside libs folder

You can get the jar file from maven the repo and drop into the libs folder in your project. You need to copy the required resources to your project as well since the jar packages don't include them.

Prerequisites

  • Maven 3.1.1+
  • Git
  • Android SDK
  • AVD image running (API level 14) or higher.
  • Android SDK with ALL packages installed
  • You may use any IDE that supports Maven. Eclipse ADT will work fine after you complete prereq step.

How To use this library

  1. Follow the Prerequisites

  2. Add a reference to your project and specify it as an Android library. If you are uncertain how to do this, click here for more information.

  3. Add the project dependency for debugging in to your project settings

  4. Update your project's AndroidManifest.xml file to include:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application
    android:allowBackup="true"
    android:debuggable="true"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme" >

    <activity
        android:name="com.microsoft.aad.adal.AuthenticationActivity"
        android:label="@string/title_login_hello_app" >
    </activity>
....
<application/>
  1. Register your WEBAPI service app in Azure Active Directory (AAD). If you're not sure what a tenant is or how you would get one, read What is a Microsoft Azure AD tenant? or Sign up for Microsoft Azure as an organization. These docs should get you started on your way to using Windows Azure AD.
  • NOTE: You need to write down the APP ID URI for the next steps
  1. Register your client native app at AAD. Select webapis in the list and give permission to previously registered WebAPI. If you need help with this step, see: Register the REST API Service Windows Azure Active Directory
  • NOTE: You will need to write down the clientId and redirectUri parameters for the next steps.
  1. Create an instance of AuthenticationContext at your main Activity. The details of this call are beyond the scope of this README, but you can get a good start by looking at the Android Native Client Sample. Below is an example:

    // Authority is in the form of https://login.windows.net/yourtenant.onmicrosoft.com
    mContext = new AuthenticationContext(MainActivity.this, authority, true); // This will use SharedPreferences as default cache
  • NOTE: mContext is a field in your activity
  1. Copy this code block to handle the end of AuthenticationActivity after user enters credentials and receives authorization code:

     @Override
     protected void onActivityResult(int requestCode, int resultCode, Intent data) {
         super.onActivityResult(requestCode, resultCode, data);
         if (mContext != null) {
             mContext.onActivityResult(requestCode, resultCode, data);
         }
     }
  2. To ask for a token, you define a callback

    • NOTE: In releases 1.13.2, 1.13.3, and 1.14.0 the onError(Exception) and onSuccess(AuthenticationResult) callbacks may not be invoked on the UI thread. This issue is tracked here.
    private AuthenticationCallback<AuthenticationResult> callback = new AuthenticationCallback<AuthenticationResult>() {
    
            @Override
            public void onError(Exception exc) {
                if (exc instanceof AuthenticationException) {
                    textViewStatus.setText("Cancelled");
                    Log.d(TAG, "Cancelled");
                } else {
                    textViewStatus.setText("Authentication error:" + exc.getMessage());
                    Log.d(TAG, "Authentication error:" + exc.getMessage());
                }
            }
    
            @Override
            public void onSuccess(AuthenticationResult result) {
                mResult = result;
    
                if (result == null || result.getAccessToken() == null
                        || result.getAccessToken().isEmpty()) {
                    textViewStatus.setText("Token is empty");
                    Log.d(TAG, "Token is empty");
                } else {
                    // request is successful
                    Log.d(TAG, "Status:" + result.getStatus() + " Expired:"
                            + result.getExpiresOn().toString());
                    textViewStatus.setText(PASSED);
                }
            }
        };
  3. Finally, ask for a token using that callback:

     mContext.acquireToken(MainActivity.this, resource, clientId, redirect, user_loginhint, PromptBehavior.Auto, "",
                    callback);

    If you're implementing your authentication logic in a Fragment, you'll need to wrap it in an IWindowComponent before passing it as a parameter, like this:

mContext.acquireToken(
    wrapFragment(MainFragment.this),
    resource,
    clientId,
    redirect,
    user_loginhint,
    PromptBehavior.Auto,
    "",
    callback);

private IWindowComponent wrapFragment(final Fragment fragment){
    return new IWindowComponent() {
        Fragment refFragment = fragment;
        @Override
        public void startActivityForResult(Intent intent, int requestCode) {
            refFragment.startActivityForResult(intent, requestCode);
        }
    };
}

Explanation of the parameters:

  • Resource is required and is the resource you are trying to access.
  • Clientid is required and comes from the AzureAD Portal.
  • You can setup redirectUri as your packagename. It is not required to be provided for the acquireToken call.
  • PromptBehavior helps to ask for credentials to skip cache and cookie.
  • Callback will be called after authorization code is exchanged for a token.

Examples can be found at Android Native Client Sample.

The Callback receives an object of type AuthenticationResult which has accesstoken, date expired, and idtoken info.

acquireTokenSilentSync

In order to get token back without prompt, you can call acquireTokenSilentSync which handles caching and token refresh without UI prompt. It provides async version as well. Note: userId required in silent call is the one you get back from the interactive call) as parameter.

mContext.acquireTokenSilentSync(String resource, String clientId, String userId);

or

mContext.acquireTokenSilent(
    String resource,
    String clientId,
    String userId,
    final AuthenticationCallback<AuthenticationResult> callback);
  1. Broker:

Microsoft Intune's Company portal App and Azure Authenticator App will provide the broker component. In order to acquire token via broker, the following requirements have to be met (please check samples\userappwithbroker for authentication via broker):

  • Starting version 1.1.14, developer has to explicitly specify set to use broker via: AuthenticationSettings.INSTANCE.setUseBroker(true);
  • Developer needs to register special redirectUri for broker usage. RedirectUri is in the format of msauth://packagename/Base64UrlencodedSignature. You can get your redirecturi for your app using the script GetBrokerRedirectURI.ps1 on Windows or brokerRedirectPrint.sh on Linux or Mac. You can also use API call mContext.getBrokerRedirectUri. Signature is related to your signing certificates.
  • If target version is lower than 23, calling app has to have the following permissions declared in the manifest:
    • GET_ACCOUNTS
    • USE_CREDENTIALS
    • MANAGE_ACCOUNTS
  • If target version is 23 or higher, USE_CREDENTIALS and MANAGE_ACCOUNTS are deprecated. But GET_ACCOUNTS is under protection level "dangerous", calling app is responsible for requesting the run-time permission; see Runtime permission request for API 23.
  • If you get an exception like "Broker related permissions are missing for GET_ACCOUNTS" with error code "DEVELOPER_BROKER_PERMISSIONS_MISSING" when acquiring token, it means you're using a very old version of ADAL(prior to V1.12.0) or broker app(Microsoft Authenticator or Intune Company Portal), please upgrade to the latest version of ADAL and broker app.
  • There must be an account existed and registered via one of the two broker apps.

AuthenticationContext provides API method to get the broker user.

String brokerAccount = mContext.getBrokerUser();

Broker user will be returned if account is valid.

Using this walkthrough, you should have what you need to successfully integrate with Azure Active Directory. For more examples of this working, visit the AzureADSamples/ repository on GitHub.

Important Information

Customization

Library project resources can be overwritten by your application resources. This happens when your app is building. For this reason, you can customize Authentication Activity layout the way you want. You need to make sure to keep the id of the controls that ADAL uses(Webview).

Broker

Broker component will be delivered with Intune's Company portal app. Account will be created in Account Manager. Account type is "com.microsoft.workaccount". It only allows single SSO account. It will create SSO cookie for this user after completing device challenge for one of the apps.

Authority Url and ADFS

ADFS is not recognized as production STS, so you need to turn of instance discovery and pass false at AuthenticationContext constructor.

Authority url needs STS instance and tenant name: https://login.windows.net/yourtenant.onmicrosoft.com

Federated sign-in failure if additional certificate downloads are required

Federated sign-in may fail when attempting to authenticate using the Azure Active Directory Authentication Library (ADAL) for Android. See Using ADAL to authenticate from Android devices fails if additional certificate downloads are required for more information.

Querying cache items

ADAL provides Default cache in SharedPrefrences with some simple cache query methods. You can get the current cache from AuthenticationContext with:

ITokenCacheStore cache = mContext.getCache();

You can also provide your cache implementation, if you want to customize it.

mContext = new AuthenticationContext(MainActivity.this, authority, true, yourCache);

PromptBehavior

ADAL provides option to specify prompt behavior. PromptBehavior.Auto will pop up UI if refresh token is invalid and user credentials are required. PromptBehavior.Always will skip the cache usage and always show UI.

Handle Doze and App Standby

Starting Android 6.0, Android introduces the new battery optimization, which will cause no network access when it's in doze and app standby mode. This wiki page contains details for doze mode and how to handle it with ADAL (https://github.com/AzureAD/azure-activedirectory-library-for-android/wiki/Handle-Doze-and-App-Standby).

Silent token request from cache and refresh

This method does not use UI pop up and not require an activity. It will return token from cache if available. If token is expired, it will try to refresh it. If refresh token is expired or failed, it will return AuthenticationException.

Future<AuthenticationResult> result = mContext.acquireTokenSilent(resource, clientid, userId, callback );

You can also make sync call with this method. You can set null to callback or use acquireTokenSilentSync.

ProGuard

If you are using ProGuard, we suggest disabling shrinking and obfuscation of ADAL classes so that our development team may assist you should issues arise. Additionally, portions of our unit and automation test code rely heavily on reflection and may not execute predictably across different versions of ProGuard.

To disable obfuscation of ADAL classes:

-keep class com.microsoft.** {
  *;
}

Diagnostics

The following are the primary sources of information for diagnosing issues:

  • Exceptions
  • Logs
  • Network traces

Also, note that correlation IDs are central to the diagnostics in the library. You can set your correlation IDs on a per request basis if you want to correlate an ADAL request with other operations in your code. If you don't set a correlations id then ADAL will generate a random one and all log messages and network calls will be stamped with the correlation id. The self generated id changes on each request.

Exceptions

This is obviously the first diagnostic. We try to provide helpful error messages. If you find one that is not helpful please file an issue and let us know. Please also provide device information such as model and SDK#.

Logs

You can configure the library to generate log messages that you can use to help diagnose issues. You configure logging by making the following call to configure a callback that ADAL will use to hand off each log message as it is generated.

Logger.getInstance().setExternalLogger(new ILogger() {
    @Override
    public void Log(String tag, String message, String additionalMessage, LogLevel level, ADALError errorCode) {
     ...
     // You can write this to logfile depending on level or errorcode.
     writeToLogFile(getApplicationContext(), tag +":" + message + "-" + additionalMessage);
    }
}

Messages can be written to a custom log file as seen below. Unfortunately, there is no standard way of getting logs from a device. There are some services that can help you with this. You can also invent your own, such as sending the file to a server.


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
swoole/swoole-src: 发布时间:2022-08-15
下一篇:
roughike/BottomBar: (Deprecated) A custom view component that mimics the new Mat ...发布时间:2022-08-15
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap