Настройка SSO (Single Sign-On) для корпоративного мобильного приложения (SAML/OIDC)

Настройка SSO (Single Sign-On) для корпоративного мобильного приложения (SAML/OIDC)

SSO в корпоративном мобильном приложении — это не просто "вход через корпоративный аккаунт". За этим стоит интеграция с Identity Provider (IdP), выбор правильного протокола, обработка токенов в соответствии с корпоративными политиками безопасности и корректная обработка сценариев принудительного logout.

OIDC vs SAML: выбор протокола

SAML 2.0 — XML-based протокол, родом из 2005 года. Широко используется в enterprise: ADFS, Okta, PingFederate. Для мобильных приложений неудобен: SAML Assertions передаются через HTTP POST (browser-based flow), что требует WebView или браузерного редиректа. Нативного мобильного SDK для SAML практически нет.

OpenID Connect (OIDC) — надстройка над OAuth 2.0, использует JWT. Нативно поддерживается в мобильных библиотеках. AppAuth — стандартная реализация Authorization Code Flow с PKCE для iOS и Android.

Если IdP поддерживает оба протокола (Okta, Azure AD, PingFederate — поддерживают), для мобильного выбираем OIDC. SAML нужен только когда IdP вынуждает: on-premise ADFS без современного обновления, или legacy корпоративная система только с SAML.

Реализация OIDC через AppAuth

Authorization Code Flow с PKCE — обязательный стандарт для мобильных (RFC 8252). Никаких implicit flow — они deprecated.

// Android — AppAuth-Android
class AuthManager(private val context: Context) {
    private val authService = AuthorizationService(context)

    fun startLogin(activity: Activity) {
        val serviceConfig = AuthorizationServiceConfiguration(
            Uri.parse("https://login.microsoftonline.com/$tenantId/oauth2/v2.0/authorize"),
            Uri.parse("https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"),
            null, // registration
            Uri.parse("https://login.microsoftonline.com/$tenantId/v2.0/.well-known/openid-configuration")
        )

        val request = AuthorizationRequest.Builder(
            serviceConfig,
            BuildConfig.CLIENT_ID,
            ResponseTypeValues.CODE,
            Uri.parse("com.company.app:/oauth2redirect")
        )
            .setScopes(
                AuthorizationRequest.SCOPE_OPENID,
                AuthorizationRequest.SCOPE_EMAIL,
                AuthorizationRequest.SCOPE_PROFILE,
                "offline_access"
            )
            .setPrompt("login") // Не кэшировать сессию IdP для корпоративных требований
            .build()

        val intent = authService.getAuthorizationRequestIntent(request)
        activity.startActivityForResult(intent, RC_AUTH)
    }

    fun handleAuthResponse(data: Intent, onSuccess: (AuthState) -> Unit, onError: (String) -> Unit) {
        val response = AuthorizationResponse.fromIntent(data)
        val exception = AuthorizationException.fromIntent(data)

        if (response != null) {
            authService.performTokenRequest(response.createTokenExchangeRequest()) { tokenResponse, ex ->
                if (tokenResponse != null) {
                    val authState = AuthState(response, tokenResponse, ex)
                    saveAuthState(authState)
                    onSuccess(authState)
                } else {
                    onError(ex?.message ?: "Token exchange failed")
                }
            }
        } else {
            onError(exception?.message ?: "Authorization failed")
        }
    }
}

На iOS аналогично через AppAuth-iOS:

let configuration = OIDServiceConfiguration(
    authorizationEndpoint: URL(string: "https://login.microsoftonline.com/\(tenantId)/oauth2/v2.0/authorize")!,
    tokenEndpoint: URL(string: "https://login.microsoftonline.com/\(tenantId)/oauth2/v2.0/token")!
)

let request = OIDAuthorizationRequest(
    configuration: configuration,
    clientId: clientId,
    scopes: [OIDScopeOpenID, OIDScopeEmail, OIDScopeProfile, "offline_access"],
    redirectURL: URL(string: "com.company.app:/oauth2redirect")!,
    responseType: OIDResponseTypeCode,
    additionalParameters: nil
)

currentAuthorizationFlow = OIDAuthState.authState(
    byPresenting: request,
    presenting: self
) { authState, error in
    if let authState = authState {
        self.authStateManager.save(authState)
    }
}

Хранение токенов и автоматический refresh

AppAuth предоставляет AuthState — объект, который управляет токенами и автоматически выполняет refresh когда access token истекает:

fun makeApiRequest(url: String) {
    authState.performActionWithFreshTokens(authService) { accessToken, _, exception ->
        if (exception != null) {
            // Refresh failed — нужен повторный логин
            navigateToLogin()
            return@performActionWithFreshTokens
        }
        // accessToken гарантированно свежий
        apiClient.get(url, bearerToken = accessToken)
    }
}

AuthState нужно сериализовать и хранить в EncryptedSharedPreferences (Android) / Keychain (iOS). Никаких SharedPreferences без шифрования — корпоративные MDM-политики это обнаруживают.

SAML через WebView

Если IdP поддерживает только SAML без OIDC-обёртки — используем custom WebView / SFSafariViewController для прохождения SAML assertion flow. Backend получает SAML Assertion, верифицирует, создаёт собственный JWT и возвращает его клиенту через Deep Link.

Это менее безопасный подход (credentials проходят через WebView), но иногда единственный вариант. Отмечаем это заказчику как технический долг и рекомендуем IdP-апгрейд.

Принудительный logout и отзыв сессии

Корпоративное требование: при увольнении сотрудника или компрометации аккаунта — немедленный отзыв доступа. Механизм: backend инвалидирует refresh token в IdP, следующий performActionWithFreshTokens возвращает ошибку, приложение перенаправляет на логин.

Для Azure AD: отзыв через Microsoft Graph POST /users/{id}/revokeSignInSessions. Для Okta: POST /api/v1/users/{userId}/sessions.

End-session endpoint — стандартный механизм OIDC для logout с IdP. Важно его вызывать при logout, иначе пользователь может повторно войти без пароля через SSO-cookie в браузере:

fun logout() {
    val endSessionRequest = EndSessionRequest.Builder(serviceConfig)
        .setIdTokenHint(authState.idToken)
        .setPostLogoutRedirectUri(Uri.parse("com.company.app:/logout"))
        .build()

    authService.performEndSessionRequest(endSessionRequest, pendingIntent)
    clearLocalAuthState()
}

Типичные проблемы

Clock skew. JWT проверяется по времени — если часы на устройстве пользователя отстают на 5+ минут, валидный токен будет отклонён как просроченный. Нужна обработка ошибки с рекомендацией синхронизировать время.

Redirect URI mismatch. Одна из самых частых ошибок на этапе настройки. Redirect URI в коде (com.company.app:/oauth2redirect) должен совпадать до символа с тем, что зарегистрировано в IdP. Custom scheme vs Universal Link — разные форматы.

Multiple IdP в одной организации. Крупные корпорации с историей M&A часто имеют несколько IdP. Нужен механизм обнаружения IdP по домену email (discovery). Поддерживается через OIDAuthorizationService.discoverConfiguration(forIssuer:).

Настройка SSO (OIDC + один IdP): 2-4 недели. Мультитенантность + несколько IdP + SAML fallback: 5-8 недель. Стоимость рассчитывается индивидуально.