Android Microsoft 인증 라이브러리 구성 파일

아티클
04/10/2024

Android MSAL(Microsoft 인증 라이브러리)은 기본 구성 JSON 파일과 함께 제공됩니다. 이 파일을 사용자 지정하여 기본 인증 기관과 같은 항목에 대한 퍼블릭 클라이언트 앱의 동작을 정의할 수 있습니다.

이 문서는 구성 파일의 다양한 설정과 MSAL 기반 앱에서 사용할 구성 파일을 지정하는 방법을 이해하는 데 도움이 됩니다.

구성 설정

일반 설정

속성	데이터 형식	Required	주의
`client_id`	문자열	예	애플리케이션 등록 페이지 에서 앱의 클라이언트 ID
`redirect_uri`	문자열	예	애플리케이션 등록 페이지 에서 앱의 리디렉션 URI
`broker_redirect_uri_registered`	부울	아니요	가능한 값: `true`, `false`
`authorities`	<권한> 나열	아니요	앱에 필요한 권한 목록
`authorization_user_agent`	AuthorizationAgent (enum)	아니요	가능한 값: `WEBVIEW`, `BROWSER`
`http`	HttpConfiguration	아니요	구성 `HttpUrlConnection` `connect_timeout` 및 `read_timeout`
`logging`	LoggingConfiguration	아니요	로깅 세부 정보 수준을 지정합니다. 선택적 구성에는 부울 값을 사용하는 `pii_enabled`와 `ERROR`, `WARNING`, `INFO` 또는 `VERBOSE`를 사용하는 `log_level`이 있습니다.

client_id

애플리케이션을 등록할 때 만든 클라이언트 ID 또는 앱 ID입니다.

redirect_uri

애플리케이션을 등록할 때 등록한 리디렉션 URI입니다. broker 앱에 대한 리디렉션 URI인 경우 broker 앱에 올바른 리디렉션 URI 형식을 사용하고 있는지 확인하려면 퍼블릭 클라이언트 앱의 리디렉션 URI를 참조하세요.

broker_redirect_uri_registered

조정된 인증을 사용하려는 경우 broker_redirect_uri_registered 속성을 true로 설정해야 합니다. 조정된 인증 시나리오에서 애플리케이션이 퍼블릭 클라이언트 앱의 리디렉션 URI에 설명된 대로 broker와 통신하기 위한 올바른 형식이 아닌 경우 애플리케이션은 리디렉션 URI의 유효성을 검사하고 시작 시 예외를 throw합니다.

인증 기관

개발자가 알고 신뢰하는 인증 기관 목록입니다. 여기에 나열된 인증 기관 외에도 MSAL은 Microsoft에 알려진 클라우드 및 기관의 목록을 가져오도록 Microsoft에 쿼리합니다. 이 인증 기관 목록에서 인증 기관 유형과 선택적인 추가 매개 변수(예: "audience")를 지정합니다. 이 매개 변수는 앱의 등록을 기반으로 하여 앱의 대상 그룹과 맞아야 합니다. 다음은 인증 기관 목록의 예입니다.

// Example AzureAD and Personal Microsoft Account
{
    "type": "AAD",
    "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
    },
    "default": true // Indicates that this is the default to use if not provided as part of the acquireToken call
},
// Example AzureAD My Organization
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMyOrg",
        "tenant_id": "contoso.com" // Provide your specific tenant ID here
    }
},
// Example AzureAD Multiple Organizations
{
    "type": "AAD",
    "audience": {
        "type": "AzureADMultipleOrgs"
    }
},
//Example PersonalMicrosoftAccount
{
    "type": "AAD",
    "audience": {
        "type": "PersonalMicrosoftAccount"
    }
}

Microsoft Entra 인증 기관 및 대상 그룹을 Microsoft ID 플랫폼 엔드포인트에 매핑

Type	대상	테넌트 ID	Authority_Url	결과 엔드포인트	주의
Microsoft Entra ID	AzureADandPersonalMicrosoftAccount			`https://login.microsoftonline.com/common`	`common`은 계정의 테넌트 별칭입니다. 특정 Microsoft Entra 테넌트 또는 Microsoft 계정 시스템과 같은 경우
Microsoft Entra ID	AzureADMyOrg	contoso.com		`https://login.microsoftonline.com/contoso.com`	Contoso.com에 있는 계정만 토큰을 획득할 수 있습니다. 확인된 도메인 또는 테넌트 GUID는 테넌트 ID로 사용될 수 있습니다.
Microsoft Entra ID	AzureADMultipleOrgs			`https://login.microsoftonline.com/organizations`	이 엔드포인트에는 Microsoft Entra 계정만 사용할 수 있습니다. Microsoft 계정은 조직의 구성원일 수 있습니다. 조직에서 리소스의 Microsoft 계정을 사용하여 토큰을 얻으려면 토큰을 가져올 조직 테넌트를 지정합니다.
Microsoft Entra ID	PersonalMicrosoftAccount			`https://login.microsoftonline.com/consumers`	Microsoft 계정만 이 엔드포인트를 사용할 수 있습니다.
B2C			결과 엔드포인트 보기	`https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/B2C_1_SISOPolicy/`	contoso.onmicrosoft.com 테넌트에 있는 계정만 토큰을 획득할 수 있습니다. 이 예제에서 B2C 정책은 인증 기관 URL 경로의 일부입니다.

참고 항목

MSAL에서는 인증 기관 유효성 검사를 사용하거나 사용하지 않도록 설정할 수 없습니다. 인증 기관은 구성을 통해 지정된 것처럼 또는 메타데이터를 통해 Microsoft에 알려진 것처럼 개발자로 알려집니다. MSAL에서 알 수 없는 인증 기관에 대한 토큰 요청을 수신하는 경우 UnknownAuthority 형식의 MsalClientException이 반환됩니다. Azure AD B2C에 대해 조정된 인증이 작동하지 않습니다.

인증 기관 속성

속성	데이터 형식	Required	주의
`type`	문자열	예	앱이 대상으로 하는 대상 그룹 또는 계정 유형을 미러링합니다. 가능한 값: `AAD`, `B2C`
`audience`	Object	아니요	유형이 `AAD`인 경우에만 적용됩니다. 앱이 대상으로 하는 ID를 지정합니다. 앱 등록의 값 사용
`authority_url`	문자열	예	유형이 `B2C`인 경우에만 필요합니다. 형식=`AAD`의 경우 선택 사항입니다. 앱에서 사용해야 하는 인증 기관 URL 또는 정책을 지정합니다.
`default`	부울 값	예	하나 이상의 인증 기관이 지정된 경우 단일 `"default":true`가 필요합니다.

대상 그룹 속성

속성	데이터 형식	Required	주의
`type`	문자열	예	앱이 대상으로 지정하려는 대상 그룹을 지정합니다. 가능한 값: `AzureADandPersonalMicrosoftAccount`, `PersonalMicrosoftAccount`, `AzureADMultipleOrgs`, `AzureADMyOrg`
`tenant_id`	문자열	예	`"type":"AzureADMyOrg"`인 경우에만 필요합니다. 다른 `type` 값의 경우 선택 사항입니다. 테넌트 도메인(예: `contoso.com`) 또는 테넌트 ID(예: `aaaabbbb-0000-cccc-1111-dddd2222eeee`)일 수 있습니다.

authorization_user_agent

계정에 로그인하거나 리소스에 대한 액세스 권한을 부여할 때 디바이스에서 포함된 웹 보기 또는 기본 브라우저를 사용할지 여부를 나타냅니다.

가능한 값:

WEBVIEW: 포함된 웹 보기를 사용합니다.
BROWSER: 디바이스에서 기본 브라우저를 사용합니다.

multiple_clouds_supported

여러 국가 클라우드를 지원하는 클라이언트의 경우 true를 지정합니다. Microsoft ID 플랫폼은 권한 부여, 토큰 상환 중 올바른 국가 클라우드로 자동으로 리디렉션됩니다. AuthenticationResult와 연결된 인증 기관을 검사하여 로그인한 계정의 국가 클라우드를 확인할 수 있습니다. AuthenticationResult는 토큰을 요청하는 리소스의 국가 클라우드 관련 엔드포인트 주소를 제공하지 않습니다.

broker_redirect_uri_registered

Microsoft ID broker와 호환되는 broker 내 리디렉션 URI를 사용하고 있는지 여부를 나타내는 부울입니다. 앱 내에서 broker를 사용하지 않으려면 false로 설정합니다.

대상 그룹이 "MicrosoftPersonalAccount"로 설정된 Microsoft Entra 기관을 사용하는 경우 broker가 사용되지 않습니다.

http

HTTP 시간 제한에 대해 다음과 같은 전역 설정을 구성합니다.

속성	데이터 형식	Required	주의
`connect_timeout`	int	아니요	시간(밀리초)
`read_timeout`	int	아니요	시간(밀리초)

logging

로깅에 대한 전역 설정은 다음과 같습니다.

속성	데이터 형식	Required	주의
`pii_enabled`	부울 값	아니요	개인 데이터를 내보낼지 여부를 지정합니다.
`log_level`	string	아니요	어떤 로그 메시지를 출력할지 지정합니다. 지원되는 로그 수준은 `ERROR`,`WARNING`,`INFO`, `VERBOSE`입니다.
`logcat_enabled`	부울 값	아니요	로깅 인터페이스 외에 로그 범주에 출력할지 여부를 지정합니다.

account_mode

앱 내에서 한 번에 사용할 수 있는 계정 수를 지정합니다. 가능한 값은 다음과 같습니다.

MULTIPLE(기본값)
SINGLE

이 설정과 일치하지 않는 계정 모드를 사용하여 PublicClientApplication을 생성하면 예외가 발생합니다.

단일 계정과 여러 계정 간의 차이점에 대한 자세한 내용은 단일 및 여러 계정 앱을 참조하세요.

browser_safelist

MSAL과 호환되는 브라우저의 허용 목록입니다. 이러한 브라우저는 사용자 지정 의도에 대한 리디렉션을 올바르게 처리합니다. 이 목록에 추가할 수 있습니다. 기본값은 아래에 표시된 기본 구성에서 제공됩니다. ``

기본 MSAL 구성 파일

MSAL과 함께 제공되는 기본 MSAL 구성은 아래와 같습니다. GitHub에서 최신 버전을 확인할 수 있습니다.

이 구성은 개발자가 제공하는 값으로 보완됩니다. 개발자가 제공하는 값은 기본값을 재정의합니다.

{
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      },
      "default": true
    }
  ],
  "authorization_user_agent": "DEFAULT",
  "multiple_clouds_supported": false,
  "broker_redirect_uri_registered": false,
  "http": {
    "connect_timeout": 10000,
    "read_timeout": 30000
  },
  "logging": {
    "pii_enabled": false,
    "log_level": "WARNING",
    "logcat_enabled": false
  },
  "shared_device_mode_supported": false,
  "account_mode": "MULTIPLE",
  "browser_safelist": [
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "45"
    },
    {
      "browser_package_name": "com.android.chrome",
      "browser_signature_hashes": [
        "cD2eF3gH4iJ5kL6mN7-oP8qR9sT=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "eF3gH4iJ5kL6mN7oP8-qR9sT0uV=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "org.mozilla.firefox",
      "browser_signature_hashes": [
        "gH4iJ5kL6mN7oP8qR9-sT0uV1wX=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "57"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "iJ5kL6mN7oP8qR9sT0-uV1wX2yZ=="
      ],
      "browser_use_customTab" : true,
      "browser_version_lower_bound": "4.0"
    },
    {
      "browser_package_name": "com.sec.android.app.sbrowser",
      "browser_signature_hashes": [
        "kL6mN7oP8qR9sT0uV1-wX2yZ3aB=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.cloudmosa.puffinFree",
      "browser_signature_hashes": [
        "mN7oP8qR9sT0uV1wX2-yZ3aB4dE="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.duckduckgo.mobile.android",
      "browser_signature_hashes": [
        "S5Av4...jAi4Q=="
      ],
      "browser_use_customTab" : false
    },
    {
      "browser_package_name": "com.explore.web.browser",
      "browser_signature_hashes": [
        "BzDzB...YHCag=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.ksmobile.cb",
      "browser_signature_hashes": [
        "lFDYx...7nouw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.microsoft.emmx",
      "browser_signature_hashes": [
        "Ivy-R...A6fVQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.browser",
      "browser_signature_hashes": [
        "FIJ3I...jWJWw=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "com.opera.mini.native",
      "browser_signature_hashes": [
        "TOTyH...mmUYQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "mobi.mgeek.TunnyBrowser",
      "browser_signature_hashes": [
        "RMVoXgjjgyjjmbj4578fcbkyyQ=="
      ],
      "browser_use_customTab" : false
    },

    {
      "browser_package_name": "org.mozilla.focus",
      "browser_signature_hashes": [
        "L72dT...q0oYA=="
      ],
      "browser_use_customTab" : false
    }
  ]
}

기본 구성 예제

다음 예제에서는 클라이언트 ID, 리디렉션 URI, broker 리디렉션이 등록되었는지 여부, 인증 기관 목록을 지정하는 기본 구성을 보여 줍니다.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "redirect_uri" : "msauth://com.microsoft.identity.client.sample.local/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount"
      }
      "default": true
    }
  ]
}

구성 파일 사용 방법

구성 파일을 만듭니다. res/raw/auth_config.json에서 사용자 지정 구성 파일을 만드는 것이 좋습니다. 하지만 원하는 위치에 배치할 수 있습니다.

PublicClientApplication을 생성할 때 MSAL에서 구성을 찾을 위치를 지정합니다. 예시:

//On Worker Thread
IMultipleAccountPublicClientApplication sampleApp = null; 
sampleApp = new PublicClientApplication.createMultipleAccountPublicClientApplication(getApplicationContext(), R.raw.auth_config);

다음을 통해 공유

Android Microsoft 인증 라이브러리 구성 파일

구성 설정

일반 설정

client_id

redirect_uri

broker_redirect_uri_registered

인증 기관

Microsoft Entra 인증 기관 및 대상 그룹을 Microsoft ID 플랫폼 엔드포인트에 매핑

인증 기관 속성

대상 그룹 속성

authorization_user_agent

multiple_clouds_supported

broker_redirect_uri_registered

http

logging

account_mode

browser_safelist

기본 MSAL 구성 파일

기본 구성 예제

구성 파일 사용 방법

피드백

추가 리소스