Apple SSO Cookbook (REST API) apple-sso-cookbook-rest-api
Introduktion Introduction
Adobe Pass Authentication REST API har stöd för plattformsautentisering med enkel inloggning (SSO) för slutanvändare av klientprogram som körs på iOS, iPadOS eller tvOS via det vi kallar Apple SSO-arbetsflöde.
Observera att det här dokumentet fungerar som ett tillägg till den befintliga REST API-dokumentationen, som finns här.
Cookbooks Cookbooks
För att Apple SSO-användarupplevelsen ska fungera måste ett program integrera ramverket Video Subscriber Account som utvecklats av Apple, och när det gäller kommunikationen med Adobe Pass Authentication REST API måste det följa de tips som presenteras nedan.
Autentisering Authentication
- Finns det en giltig Adobe-autentiseringstoken?
- Är användaren inloggad via enkel inloggning för plattform?
- Hämta Adobe-konfiguration
- Starta arbetsflödet för enkel inloggning på plattformen med Adobe config
- Har användaren loggat in?
- Hämta en profilbegäran från Adobe för det valda MVPD-programmet
- Vidarebefordra Adobe-begäran till enkel inloggning för plattformen för att erhålla profilen
- Exchange-plattformens SSO-profil för en Adobe-autentiseringstoken
- Genereras Adobe-token korrekt?
- Starta autentiseringsarbetsflöde för andra skärmen
- Fortsätt med auktoriseringsflöden
Steg: "Finns det en giltig token för autentisering i Adobe?" Is_there_a_valid_Adobe_authentication_token
Steg:"Är användaren inloggad via plattformens SSO?" Is_the_user_logged_in_via_Platform_SSO
- Programmet måste kontrollera om användaren har behörighet att komma åt användarens prenumerationsinformation och fortsätta endast om användaren tillåter det.
- Programmet måste skicka en förfrågan för prenumerantkontoinformation.
- Programmet måste vänta och bearbeta metadata-informationen.
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to refrain from prompting the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = false;
// Submit the request for subscriber account information - accountProviderIdentifier.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
// The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
// The vsaMetadata!.authenticationExpirationDate should be compared against current date.
...
// The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
// The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
...
// The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
// The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
...
// Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
...
// Continue with the "Forward the Adobe request to Platform SSO to obtain the profile" step.
...
} else {
// The user is not authenticated at platform level, continue with the "Fetch Adobe configuration" step.
...
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
Steg: "Hämta Adobe-konfiguration" Fetch_Adobe_configuration
enablePlatformServices
, boardingStatus
, displayInPlatformPicker
, platformMappingId
, requiredMetadataFields
och observera de kommentarer som presenteras i kodfragment från andra steg.Steg"Initiera SSO-arbetsflöde för plattformen med Adobe config" Initiate_Platform_SSO_workflow_with_Adobe_config
- Programmet måste kontrollera om användaren har behörighet att komma åt användarens prenumerationsinformation och fortsätta endast om användaren tillåter det.
- Programmet måste tillhandahålla delegate för VSAccountManager.
- Programmet måste skicka en förfrågan för prenumerantkontoinformation.
- Programmet måste vänta och bearbeta metadata-informationen.
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
// This must be a class implementing the VSAccountManagerDelegate protocol.
let videoSubscriberAccountManagerDelegate: VideoSubscriberAccountManagerDelegate = VideoSubscriberAccountManagerDelegate();
videoSubscriberAccountManager.delegate = videoSubscriberAccountManagerDelegate;
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to prompt the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = true;
// This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=sv) service response in order to filter the TV providers from the Apple picker.
vsaMetadataRequest.supportedAccountProviderIdentifiers = supportedAccountProviderIdentifiers;
// This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=sv) service response in order to sort the TV providers from the Apple picker.
if #available(iOS 11.0, tvOS 11, *) {
vsaMetadataRequest.featuredAccountProviderIdentifiers = featuredAccountProviderIdentifiers;
}
// Submit the request for subscriber account information - accountProviderIdentifier.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
// This represents the checks for the "Is user login successful?" step.
if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
// The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
// The vsaMetadata!.authenticationExpirationDate should be compared against current date.
...
// The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
// The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
...
// The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
// The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
...
// Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
...
// Continue with the "Forward the Adobe request to Platform SSO to obtain the profile" step.
...
} else {
// The user is not authenticated at platform level.
if (vsaError != nil) {
// The application can check to see if the user selected a provider which is present in Apple picker, but the provider is not onboarded in platform SSO.
if let error: NSError = (vsaError! as NSError), error.code == 1, let appleMsoId = error.userInfo["VSErrorInfoKeyUnsupportedProviderIdentifier"] as! String? {
var mvpd: Mvpd? = nil;
// The requestor.mvpds must be computed during the "Fetch Adobe configuration" step.
for provider in requestor.mvpds {
if provider.platformMappingId == appleMsoId {
mvpd = provider;
break;
}
}
if mvpd != nil {
// Continue with the "Initiate second screen authentcation workflow" step, but you can skip prompting the user with your MVPD picker and use the mvpd selection, therefore creating a better UX.
...
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
Steg:"Har användarinloggningen slutförts?" Is_user_login_successful
vsaMetadata!.accountProviderIdentifier
innehåller ett giltigt värde och det aktuella datumet inte har passerat värdet vsaMetadata!.authenticationExpirationDate
.Steg"Hämta en profilförfrågan från Adobe för det valda MVPD" Obtain_a_profile_request_from_Adobe_for_the_selected_MVPD
platformMappingId
med avseende på konfigurationen för Adobe Pass-autentisering. Därför måste programmet fastställa MVPD ID-egenskapsvärdet med hjälp av värdet platformMappingId
via tjänsten Tillhandahåll MVPD-lista för Adobe Pass-autentisering.Steg:"Vidarebefordra Adobe-begäran till plattformens SSO för att hämta profilen" Forward_the_Adobe_request_to_Platform_SSO_to_obtain_the_profile
- Programmet måste kontrollera om användaren har behörighet att komma åt användarens prenumerationsinformation och fortsätta endast om användaren tillåter det.
- Programmet måste skicka en förfrågan för prenumerantkontoinformation.
- Programmet måste vänta och bearbeta metadata-informationen.
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is going to include subscription account information which should match the provider determined in a previous step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is going to include subscription account information which should match the provider determined in a previous step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to refrain from prompting the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = false;
// This are the user metadata fields expected to be available on a successful login and are determined from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=sv) service. Look for the requiredMetadataFields associated with the provider determined in a previous step.
vsaMetadataRequest.attributeNames = requiredMetadataFields;
// This is the payload from [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/retrieve-profilerequest.html?lang=sv) service.
vsaMetadataRequest.verificationToken = profileRequestPayload;
// Submit the request for subscriber account information.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
if (vsaMetadata != nil && vsaMetadata!.samlAttributeQueryResponse != nil) {
var samlResponse: String? = vsaMetadata!.samlAttributeQueryResponse!;
// Remove new lines, new tabs and spaces.
samlResponse = samlResponse?.replacingOccurrences(of: "[ \\t]+", with: " ", options: String.CompareOptions.regularExpression);
samlResponse = samlResponse?.components(separatedBy: CharacterSet.newlines).joined(separator: "");
samlResponse = samlResponse?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines);
// Base64 encode.
samlResponse = samlResponse?.data(using: .utf8)?.base64EncodedString(options: []);
// URL encode. Please be aware not to double URL encode it further.
samlResponse = samlResponse?.addingPercentEncoding(withAllowedCharacters: CharacterSet.init(charactersIn: "!*'();:@&=+$,/?%#[]").inverted);
// Continue with the "Exchange the Platform SSO profile for an Adobe authentication token" step.
...
} else {
// Fallback to regular authentication workflow.
...
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
Steg:"Byt ut plattformens SSO-profil för en autentiseringstoken för Adobe" Exchange_the_Platform_SSO_profile_for_an_Adobe_authentication_token
vsaMetadata!.samlAttributeQueryResponse!
representerar SAMLResponse
, som måste skickas på Token Exchange och som kräver strängmanipulering och kodning (Base64-kodad och URL-kodad efteråt) innan anropet görs.Steg:"Har Adobe-token genererats utan fel?" Is_Adobe_token_generated_successfully
204 No Content
som anger att token har skapats och är klar att användas för auktoriseringsflödena.Steg:"Initiera ett andra autentiseringsarbetsflöde för skärmen" Initiate_second_screen_authentication_workflow
Viktigt!"Arbetsflöde för autentisering på andra skärmen" är lämplig för AppleTV-program, medan"Arbetsflöde för autentisering på första skärmen"/"Vanligt autentiseringsarbetsflöde" skulle vara lämpligare för iPhone och iPad.
Registreringskodbegäran, Initiera autentisering och REST API Retrieve Authentication Token eller Kontrollera autentiseringstoken.
- Programmet måste hämta en registreringskod och presentera den för slutanvändaren på den första enheten (skärmen).
- Programmet måste starta avsökningen för att bekräfta autentiseringstillståndet på den första enheten (skärmen) när registreringskoden har hämtats.
- Ett annat program måste initiera autentisering på en andra enhet (skärm) när registreringskoden används.
- Programmet måste stoppa avsökningen på den första enheten (skärmen) när autentiseringstoken genereras.
- Programmet måste hämta en registreringskod som inte ska visas för slutanvändaren på den första enheten (skärmen).
- Programmet måste initiera autentisering på den första enheten (skärmen) med registreringskoden och en WKWebView eller en SFSafariViewController -komponent.
- Programmet måste starta avsökningen för att känna till autentiseringstillståndet på den första enheten (skärmen) när WKWebView eller SFSafariViewController -komponenten stängs.
- Programmet måste stoppa avsökningen på den första enheten (skärmen) när autentiseringstoken genereras.
Steg:"Fortsätt med auktoriseringsflöden" Proceed_with_authorization_flows
Utloggning Logout
Ramverket Video Subscriber Account innehåller inte något API för att logga ut personer som har loggat in på sitt TV-leverantörskonto på enhetssystemnivå. För att utloggningen ska få full effekt måste slutanvändaren därför uttryckligen logga ut från Settings -> TV Provider
på iOS/iPadOS eller Settings -> Accounts -> TV Provider
på tvOS. Det andra alternativet som användaren skulle ha möjlighet att återkalla behörigheten att få åtkomst till användarens prenumerationsinformation från det specifika avsnittet för programinställningar (TV-leverantörsåtkomst).
- Programmet måste avgöra om autentiseringen har skett som ett resultat av en inloggning via plattformens SSO eller inte, med hjälp av tokenSource användarens metadata från Adobe Pass Authentication-tjänsten.
- Programmet måste instruera/uppmana användaren att explicit logga ut från
Settings -> Accounts -> TV Provider
på tvOS only om värdet "tokenSource" är lika med Apple". - Programmet måste initiera utloggningen från Adobe Pass-autentiseringstjänsten med ett direkt HTTP-anrop. Detta skulle inte underlätta sessionsrensning på MVPD-sidan.
- Programmet måste avgöra om autentiseringen har skett som ett resultat av en inloggning via plattformens SSO eller inte, med hjälp av tokenSource användarens metadata från Adobe Pass-autentiseringstjänsten.
- Programmet måste instruera/uppmana användaren att explicit logga ut från
Settings -> TV Provider
på iOS/iPadOS only om värdet "tokenSource" är lika med "Apple". - Programmet måste initiera utloggningen från Adobe Pass-autentiseringstjänsten med en WKWebView eller en SFSafariViewController -komponent. Detta underlättar sessionssanering på den mobila dokumentationssidan.