Dostosowywanie oświadczeń wystawionych w tokenie internetowym JSON (JWT) dla aplikacji dla przedsiębiorstw
Aplikacja Platforma tożsamości Microsoft obsługuje logowanie jednokrotne (SSO) z większością wstępnie zintegrowanych aplikacji w galerii aplikacji Firmy Microsoft Entra i aplikacji niestandardowych. Gdy użytkownik uwierzytelnia się w aplikacji za pośrednictwem Platforma tożsamości Microsoft przy użyciu protokołu OIDC, wysyła token do aplikacji. Aplikacja weryfikuje token i używa go do logowania użytkownika zamiast monitowania o podanie nazwy użytkownika i hasła.
Te tokeny internetowe JSON (JWT) używane przez aplikacje OIDC i OAuth zawierają informacje o użytkowniku znanym jako oświadczenia. Oświadczenie to informacje, które dostawca tożsamości stwierdza o użytkowniku wewnątrz tokenu, który wystawia dla tego użytkownika. W odpowiedzi OIDC dane oświadczeń są zwykle zawarte w tokenie identyfikatora wystawionym przez dostawcę tożsamości w postaci zestawu JWT.
Wyświetlanie lub edytowanie oświadczeń
Napiwek
Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.
Opcjonalne oświadczenia JWT można skonfigurować w oryginalnej rejestracji aplikacji, ale można je również skonfigurować w aplikacji dla przedsiębiorstw. Aby wyświetlić lub edytować oświadczenia wystawione w usłudze JWT do aplikacji:
- Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
- Przejdź do sekcji Identity>Applications Enterprise Applications>Wszystkie aplikacje.>
- Wybierz aplikację, wybierz pozycję Logowanie jednokrotne w menu po lewej stronie, a następnie wybierz pozycję Edytuj w sekcji Atrybuty i oświadczenia .
Aplikacja może wymagać dostosowania oświadczeń z różnych powodów. Na przykład gdy aplikacja wymaga innego zestawu identyfikatorów URI oświadczeń lub wartości oświadczeń. Korzystając z sekcji Atrybuty i oświadczenia, możesz dodać lub usunąć oświadczenie dla aplikacji. Można również utworzyć oświadczenie niestandardowe specyficzne dla aplikacji na podstawie przypadku użycia.
W poniższych krokach opisano sposób przypisywania wartości stałej:
- Wybierz oświadczenie, które chcesz zmodyfikować.
- Wprowadź stałą wartość bez cudzysłowów w atrybucie Source zgodnie z twoją organizacją, a następnie wybierz pozycję Zapisz.
Przegląd atrybutów wyświetla stałą wartość.
Przekształcenia oświadczeń specjalnych
Możesz użyć następujących specjalnych funkcji przekształceń oświadczeń.
| Function | opis |
|---|---|
| ExtractMailPrefix() | Usuwa sufiks domeny z adresu e-mail lub głównej nazwy użytkownika. Ta funkcja wyodrębnia tylko pierwszą część nazwy użytkownika. Na przykład joe_smith zamiast joe_smith@contoso.com. |
| ToLower() | Konwertuje znaki wybranego atrybutu na małe litery. |
| ToUpper() | Konwertuje znaki wybranego atrybutu na wielkie litery. |
Dodawanie oświadczeń specyficznych dla aplikacji
Aby dodać oświadczenia specyficzne dla aplikacji:
- W obszarze Atrybuty użytkownika i oświadczenia wybierz pozycję Dodaj nowe oświadczenie , aby otworzyć stronę Zarządzanie oświadczeniami użytkowników.
- Wprowadź nazwę oświadczeń. Wartość nie musi być ściśle zgodna ze wzorcem identyfikatora URI. Jeśli potrzebujesz wzorca identyfikatora URI, możesz umieścić go w polu Przestrzeń nazw .
- Wybierz źródło, w którym oświadczenie ma pobrać jego wartość. Możesz wybrać atrybut użytkownika z listy rozwijanej atrybutu źródłowego lub zastosować przekształcenie do atrybutu użytkownika przed jego emisją jako oświadczenie.
Przekształcenia oświadczeń
Aby zastosować przekształcenie do atrybutu użytkownika:
- W obszarze Zarządzanie oświadczeniem wybierz pozycję Przekształcenie jako źródło oświadczeń, aby otworzyć stronę Zarządzanie transformacją.
- Wybierz funkcję z listy rozwijanej przekształcenia. W zależności od wybranej funkcji podaj parametry i stałą wartość do obliczenia w transformacji.
- Traktuj źródło jako wielowartościowe wskazuje, czy transformacja jest stosowana do wszystkich wartości, czy tylko do pierwszych. Domyślnie pierwszy element w oświadczeniu z wieloma wartościami jest stosowany przekształcenia. Po zaznaczeniu tego pola gwarantuje, że zostanie on zastosowany do wszystkich. To pole wyboru jest włączone tylko dla atrybutów wielowartych. Na przykład
user.proxyaddresses. - Aby zastosować wiele przekształceń, wybierz pozycję Dodaj przekształcenie. Do oświadczenia można zastosować maksymalnie dwie przekształcenia. Na przykład można najpierw wyodrębnić prefiks wiadomości e-mail z pliku
user.mail. Następnie utwórz wielkie litery ciągu.
Do przekształcania oświadczeń można użyć następujących funkcji.
| Function | opis |
|---|---|
| ExtractMailPrefix() | Usuwa sufiks domeny z adresu e-mail lub głównej nazwy użytkownika. Ta funkcja wyodrębnia tylko pierwszą część nazwy użytkownika. Na przykład joe_smith zamiast joe_smith@contoso.com. |
| Join() | Tworzy nową wartość, łącząc dwa atrybuty. Opcjonalnie można użyć separatora między dwoma atrybutami. W przypadku przekształcenia oświadczenia NameID funkcja Join() ma określone zachowanie, gdy dane wejściowe przekształcenia mają część domeny. Usuwa część domeny z danych wejściowych przed dołączeniem go do separatora i wybranego parametru. Jeśli na przykład dane wejściowe przekształcenia to joe_smith@contoso.com , a separator to @ , a parametr to fabrikam.com, ta kombinacja danych wejściowych powoduje wynik .joe_smith@fabrikam.com |
| ToLowercase() | Konwertuje znaki wybranego atrybutu na małe litery. |
| ToUppercase() | Konwertuje znaki wybranego atrybutu na wielkie litery. |
| Contains() | Zwraca atrybut lub stałą, jeśli dane wejściowe są zgodne z określoną wartością. W przeciwnym razie możesz określić inne dane wyjściowe, jeśli nie ma dopasowania. Jeśli na przykład chcesz emitować oświadczenie, w którym wartość jest adresem e-mail użytkownika, jeśli zawiera domenę @contoso.com, w przeciwnym razie chcesz wyświetlić główną nazwę użytkownika. Aby wykonać tę funkcję, należy skonfigurować następujące wartości:Parametr 1(wejście): user.email Wartość: "@contoso.com" Parametr 2 (dane wyjściowe): user.email Parametr 3 (dane wyjściowe, jeśli nie ma dopasowania): user.userprincipalname |
| EndWith() | Zwraca atrybut lub stałą, jeśli dane wejściowe kończą się określoną wartością. W przeciwnym razie możesz określić inne dane wyjściowe, jeśli nie ma dopasowania. Jeśli na przykład chcesz emitować oświadczenie, w którym wartość jest identyfikatorem pracownika użytkownika, jeśli identyfikator pracownika kończy się wartością 000, w przeciwnym razie chcesz wyświetlić atrybut rozszerzenia. Aby wykonać tę funkcję, należy skonfigurować następujące wartości:Parametr 1(input): user.employeeid Wartość: "000" Parametr 2 (dane wyjściowe): user.employeeid Parametr 3 (dane wyjściowe, jeśli nie ma dopasowania): user.extensionattribute1 |
| StartWith() | Zwraca atrybut lub stałą, jeśli dane wejściowe zaczynają się od określonej wartości. W przeciwnym razie możesz określić inne dane wyjściowe, jeśli nie ma dopasowania. Jeśli na przykład chcesz emitować oświadczenie, w którym wartość jest identyfikatorem pracownika użytkownika, jeśli kraj/region zaczyna się od US, w przeciwnym razie chcesz wyświetlić atrybut rozszerzenia. Aby wykonać tę funkcję, należy skonfigurować następujące wartości:Parametr 1(input): user.country Wartość: "USA" Parametr 2 (dane wyjściowe): user.employeeid Parametr 3 (dane wyjściowe, jeśli nie ma dopasowania): user.extensionattribute1 |
| Extract() — po dopasowaniu | Zwraca podciąg po jego dopasowaniu do określonej wartości. Jeśli na przykład wartość danych wejściowych to Finance_BSimon, zgodna wartość to Finance_, dane wyjściowe oświadczenia to BSimon. |
| Extract() — przed dopasowaniem | Zwraca podciąg, dopóki nie pasuje do określonej wartości. Jeśli na przykład wartość danych wejściowych to BSimon_US, zgodna wartość to _US, dane wyjściowe oświadczenia to BSimon. |
| Extract() — między dopasowaniem | Zwraca podciąg, dopóki nie pasuje do określonej wartości. Jeśli na przykład wartość danych wejściowych to Finance_BSimon_US, pierwszą zgodną wartością jest Finance_, druga zgodna wartość to _US, dane wyjściowe oświadczenia to BSimon. |
| ExtractAlpha() — prefiks | Zwraca prefiks alfabetyczny część ciągu. Jeśli na przykład wartość danych wejściowych to BSimon_123, zwraca BSimonwartość . |
| ExtractAlpha() — sufiks | Zwraca sufiks alfabetyczny części ciągu. Jeśli na przykład wartość danych wejściowych to 123_Simon, zwraca Simonwartość . |
| ExtractNumeric() — prefiks | Zwraca prefiks liczbowej części ciągu. Jeśli na przykład wartość danych wejściowych to 123_BSimon, zwraca 123wartość . |
| ExtractNumeric() — sufiks | Zwraca część liczbową sufiksu ciągu. Jeśli na przykład wartość danych wejściowych to BSimon_123, zwraca 123wartość . |
| IfEmpty() | Zwraca atrybut lub stałą, jeśli dane wejściowe mają wartość null lub są puste. Jeśli na przykład chcesz wyświetlić atrybut przechowywany w atrybucie rozszerzenia, jeśli identyfikator pracownika dla danego użytkownika jest pusty. Aby wykonać tę funkcję, skonfiguruj następujące wartości: Parametr 1 (dane wejściowe): user.employeeid Parametr 2 (dane wyjściowe): user.extensionattribute1 Parametr 3 (dane wyjściowe, jeśli nie ma dopasowania): user.employeeid |
| IfNotEmpty() | Zwraca atrybut lub stałą, jeśli dane wejściowe nie mają wartości null ani nie są puste. Jeśli na przykład chcesz wyświetlić atrybut przechowywany w atrybucie rozszerzenia, jeśli identyfikator pracownika dla danego użytkownika nie jest pusty. Aby wykonać tę funkcję, należy skonfigurować następujące wartości: Parametr 1 (dane wejściowe): user.employeeid Parametr 2 (dane wyjściowe): user.extensionattribute1 |
| Podciąg() — stała długość | Wyodrębnia części typu oświadczenia ciągu, zaczynając od znaku w określonej pozycji, i zwraca określoną liczbę znaków. SourceClaim — źródło oświadczenia przekształcenia, które należy wykonać. StartIndex — pozycja początkowego typu zero podciągów w tym wystąpieniu. Length — długość znaków podciągów. Na przykład: sourceClaim — PleaseExtractThisNow StartIndex — 6 Długość — 11 Dane wyjściowe: ExtractThis |
| Podciąg() — EndOfString | Wyodrębnia części typu oświadczenia ciągu, zaczynając od znaku w określonej pozycji, i zwraca resztę oświadczenia z określonego indeksu początkowego. SourceClaim — źródło oświadczenia przekształcenia. StartIndex — pozycja początkowego typu zero podciągów w tym wystąpieniu. Na przykład: sourceClaim — PleaseExtractThisNow StartIndex — 6 Dane wyjściowe: ExtractThisNow |
| RegexReplace() | Przekształcenie RegexReplace() akceptuje jako parametry wejściowe: - Parametr 1: atrybut użytkownika jako dane wejściowe wyrażenia regularnego - Opcja zaufania źródle jako wielowartościowa - Wzorzec wyrażeń regularnych - Wzorzec zastępowania. Wzorzec zamiany może zawierać statyczny format tekstu wraz z odwołaniem wskazującym grupy danych wyjściowych wyrażeń regularnych i więcej parametrów wejściowych. |
Jeśli potrzebujesz innych przekształceń, prześlij swój pomysł na forum opinii w witrynie Microsoft Entra ID w kategorii aplikacji SaaS.
Przekształcanie oświadczeń opartych na wyrażeniach regularnych
Na poniższej ilustracji przedstawiono przykład pierwszego poziomu transformacji:
Poniższa tabela zawiera informacje o pierwszym poziomie przekształceń. Akcje wymienione w tabeli odpowiadają etykietom na poprzedniej ilustracji. Wybierz pozycję Edytuj , aby otworzyć blok przekształcania oświadczeń.
| Akcja | Pole | opis |
|---|---|---|
| 1 | Transformation |
Wybierz opcję RegexReplace() z opcji Przekształcanie, aby użyć metody przekształcania oświadczeń opartych na wyrażeniach regularnych na potrzeby przekształcania oświadczeń. |
| 2 | Parameter 1 |
Dane wejściowe przekształcenia wyrażenia regularnego. Na przykład user.mail, który ma adres e-mail użytkownika, taki jak admin@fabrikam.com. |
| 3 | Treat source as multivalued |
Niektóre wejściowe atrybuty użytkownika mogą być atrybutami użytkownika o wielu wartościach. Jeśli wybrany atrybut użytkownika obsługuje wiele wartości, a użytkownik chce użyć wielu wartości do przekształcenia, musi wybrać opcję Traktuj źródło jako wielowartościowe. W przypadku wybrania wszystkie wartości są używane do dopasowania wyrażenia regularnego, w przeciwnym razie jest używana tylko pierwsza wartość. |
| 100 | Regex pattern |
Wyrażenie regularne, które jest oceniane względem wartości atrybutu użytkownika wybranego jako parametr 1. Na przykład wyrażenie regularne w celu wyodrębnienia aliasu użytkownika z adresu e-mail użytkownika jest reprezentowane jako (?'domain'^.*?)(?i)(\@fabrikam\.com)$. |
| 5 | Add additional parameter |
Do przekształcenia można użyć więcej niż jednego atrybutu użytkownika. Następnie wartości atrybutów zostaną scalone z danymi wyjściowymi przekształcenia regularnego. Obsługiwane są maksymalnie pięć dodatkowych parametrów. |
| 6 | Replacement pattern |
Wzorzec zastępczy to szablon tekstowy, który zawiera symbole zastępcze dla wyniku wyrażenia regularnego. Wszystkie nazwy grup muszą być opakowane wewnątrz nawiasów klamrowych, takich jak {group-name}. Załóżmy, że administracja chce użyć aliasu użytkownika z inną nazwą domeny, na przykład xyz.com i scalić nazwę kraju z nim. W tym przypadku wzorzec zastępczy to {country}.{domain}@xyz.com, gdzie {country} jest wartością parametru wejściowego i {domain} jest wynikiem grupy z oceny wyrażenia regularnego. W takim przypadku oczekiwany wynik to US.swmal@xyz.com. |
Na poniższej ilustracji przedstawiono przykład drugiego poziomu transformacji:
Poniższa tabela zawiera informacje o drugim poziomie przekształceń. Akcje wymienione w tabeli odpowiadają etykietom na poprzedniej ilustracji.
| Akcja | Pole | opis |
|---|---|---|
| 1 | Transformation |
Przekształcenia oświadczeń opartych na wyrażeniach regularnych nie są ograniczone do pierwszej transformacji i mogą być również używane jako transformacja drugiego poziomu. Dowolną inną metodę przekształcania można użyć jako pierwszej transformacji. |
| 2 | Parameter 1 |
Jeśli funkcja RegexReplace() jest wybrana jako przekształcenie drugiego poziomu, dane wyjściowe transformacji pierwszego poziomu są używane jako dane wejściowe dla transformacji drugiego poziomu. Aby zastosować przekształcenie, drugie wyrażenie wyrażeń wyrażeń regularnych powinno być zgodne z danymi wyjściowymi pierwszego przekształcenia. |
| 3 | Regex pattern |
Wzorzec wyrażenia regularnego jest wyrażeniem regularnym dla przekształcenia drugiego poziomu. |
| 100 | Parameter input |
Dane wejściowe atrybutu użytkownika dla przekształceń drugiego poziomu. |
| 5 | Parameter input |
Administratorzy mogą usunąć wybrany parametr wejściowy, jeśli nie będą już tego potrzebować. |
| 6 | Replacement pattern |
Wzorzec zastępczy to szablon tekstowy, który zawiera symbole zastępcze dla nazwy grupy wyników wyrażeń regularnych, nazwy grupy parametrów wejściowych i statycznej wartości tekstowej. Wszystkie nazwy grup muszą być opakowane wewnątrz nawiasów klamrowych, takich jak {group-name}. Załóżmy, że administracja chce użyć aliasu użytkownika z inną nazwą domeny, na przykład xyz.com i scalić nazwę kraju z nim. W tym przypadku wzorzec zastępczy to {country}.{domain}@xyz.com, gdzie {country} jest wartością parametru wejściowego i {domain} jest wynikiem grupy z oceny wyrażenia regularnego. W takim przypadku oczekiwany wynik to US.swmal@xyz.com. |
| 7 | Test transformation |
Przekształcenie RegexReplace() jest oceniane tylko wtedy, gdy wartość wybranego atrybutu użytkownika parametru 1 jest zgodna z wyrażeniem regularnym podanym w polu tekstowym Wzorzec wyrażenia regularnego. Jeśli nie są one zgodne, domyślna wartość oświadczenia zostanie dodana do tokenu. Aby zweryfikować wyrażenie regularne względem wartości parametru wejściowego, środowisko testowe jest dostępne w bloku przekształcania. To środowisko testowe działa tylko na fikcyjnych wartościach. Gdy są używane więcej parametrów wejściowych, nazwa parametru jest dodawana do wyniku testu zamiast wartości rzeczywistej. Aby uzyskać dostęp do sekcji testu, wybierz pozycję Przetestuj przekształcenie. |
Na poniższej ilustracji przedstawiono przykład testowania przekształceń:
Poniższa tabela zawiera informacje dotyczące testowania przekształceń. Akcje wymienione w tabeli odpowiadają etykietom na poprzedniej ilustracji.
| Akcja | Pole | opis |
|---|---|---|
| 1 | Test transformation |
Wybierz przycisk Zamknij lub (X), aby ukryć sekcję testu i ponownie wyrenderować przycisk przekształcenia Testuj ponownie w bloku. |
| 2 | Test regex input |
Akceptuje dane wejściowe używane do oceny testu wyrażeń regularnych. W przypadku, gdy przekształcenie oświadczeń opartych na wyrażeniach regularnych jest skonfigurowane jako przekształcenie drugiego poziomu, podaj wartość, która jest oczekiwaną wartością wyjściową pierwszego przekształcenia. |
| 3 | Run test |
Po podaniu danych wejściowych wyrażeń regularnych testowych i skonfigurowaniu wzorca wyrażeń regularnych wzorzec zastąpienia i parametrów wejściowych wyrażenie można ocenić, wybierając pozycję Uruchom test. |
| 100 | Test transformation result |
Jeśli ocena zakończy się pomyślnie, dane wyjściowe przekształcenia testowego są renderowane względem etykiety wyniku przekształcenia testowego. |
| 5 | Remove transformation |
Przekształcenie drugiego poziomu można usunąć, wybierając pozycję Usuń przekształcenie. |
| 6 | Specify output if no match |
Po skonfigurowaniu wartości wejściowej wyrażenia regularnego względem parametru 1, który nie jest zgodny z wyrażeniem regularnym, przekształcenie zostanie pominięte. W takich przypadkach można skonfigurować atrybut alternatywnego użytkownika, który jest dodawany do tokenu dla oświadczenia, zaznaczając opcję Określ dane wyjściowe, jeśli nie są zgodne. |
| 7 | Parameter 3 |
Jeśli atrybut alternatywnego użytkownika musi być zwracany, gdy nie ma dopasowania i Określ dane wyjściowe, jeśli nie jest zaznaczone dopasowanie , można wybrać alternatywny atrybut użytkownika przy użyciu listy rozwijanej. Ta lista rozwijana jest dostępna dla parametru 3 (dane wyjściowe, jeśli nie są zgodne). |
| 8 | Summary |
W dolnej części bloku zostanie wyświetlone pełne podsumowanie formatu, które wyjaśnia znaczenie przekształcenia w prostym tekście. |
| 9 | Add |
Po zweryfikowaniu ustawień konfiguracji przekształcenia można je zapisać w zasadach oświadczeń, wybierając pozycję Dodaj. Wybierz pozycję Zapisz w bloku Zarządzaj oświadczeniem, aby zapisać zmiany. |
Przekształcenie RegexReplace() jest również dostępne dla przekształceń oświadczeń grupy.
Walidacje przekształceń
Komunikat zawiera więcej informacji, gdy po wybraniu pozycji Dodaj lub Uruchom test wystąpią następujące warunki:
- Użyto parametrów wejściowych z zduplikowanymi atrybutami użytkownika.
- Znaleziono nieużywane parametry wejściowe. Zdefiniowane parametry wejściowe powinny mieć odpowiednie użycie w tekście wzorca zastępczego.
- Podane dane wejściowe wyrażeń regularnych testu nie są zgodne z podanym wyrażeniem regularnym.
- Nie można odnaleźć źródeł dla grup we wzorcu zastępowania.
Emituj oświadczenia na podstawie warunków
Źródło oświadczenia można określić na podstawie typu użytkownika i grupy, do której należy użytkownik.
Typ użytkownika może być:
- Dowolne — wszyscy użytkownicy mogą uzyskiwać dostęp do aplikacji.
- Członkowie: natywny członek dzierżawy
- Wszyscy goście: użytkownik przeniósł się z organizacji zewnętrznej z identyfikatorem Microsoft Entra ID lub bez tego identyfikatora.
- Goście firmy Microsoft Entra: użytkownik-gość należy do innej organizacji przy użyciu identyfikatora Entra firmy Microsoft.
- Goście zewnętrzni: użytkownik-gość należy do organizacji zewnętrznej, która nie ma identyfikatora Entra firmy Microsoft.
Jednym ze scenariuszy, w których typ użytkownika jest przydatny, jest to, że źródło oświadczenia jest inne dla gościa i pracownika, który uzyskuje dostęp do aplikacji. Możesz określić, że jeśli użytkownik jest pracownikiem, pobierz identyfikator NameID z user.email. Jeśli użytkownik jest gościem, identyfikator NameID pochodzi z user.extensionattribute1.
Aby dodać warunek oświadczenia:
- W obszarze Zarządzanie oświadczeniem rozwiń warunki oświadczenia.
- Wybierz typ użytkownika.
- Wybierz grupy, do których powinien należeć użytkownik. Możesz wybrać maksymalnie 50 unikatowych grup we wszystkich oświadczeniach dla danej aplikacji.
- Wybierz źródło, w którym oświadczenie ma pobrać jego wartość. Możesz wybrać atrybut użytkownika z listy rozwijanej atrybutu źródłowego lub zastosować przekształcenie do atrybutu użytkownika przed jego emisją jako oświadczenie.
Kolejność dodawania warunków jest ważna. Firma Microsoft Entra najpierw ocenia wszystkie warunki ze źródłem Attribute , a następnie ocenia wszystkie warunki ze źródłem Transformation , aby zdecydować, która wartość ma być emitowa w oświadczeniu. Identyfikator Entra firmy Microsoft ocenia warunki z tym samym źródłem od góry do dołu. Oświadczenie emituje ostatnią wartość zgodną z wyrażeniem w oświadczeniu. Przekształcenia, takie jak IsNotEmpty i Contains działają jak ograniczenia.
Na przykład Britta Simon jest użytkownikiem-gościem w dzierżawie firmy Contoso. Britta należy do innej organizacji, która używa również identyfikatora Microsoft Entra ID. Biorąc pod uwagę następującą konfigurację aplikacji Fabrikam, gdy britta próbuje zalogować się do firmy Fabrikam, Platforma tożsamości Microsoft ocenia warunki.
Najpierw Platforma tożsamości Microsoft sprawdza, czy typ użytkownika Britta to Wszyscy goście. Ponieważ typ to Wszyscy goście, Platforma tożsamości Microsoft przypisuje źródło oświadczenia do user.extensionattribute1. Po drugie, Platforma tożsamości Microsoft sprawdza, czy typ użytkownika Britta jest gościem firmy Microsoft Entra. Ponieważ typ to Wszyscy goście, Platforma tożsamości Microsoft przypisuje źródło oświadczenia do user.mail. Na koniec oświadczenie jest emitowane z wartością user.mail dla Britta.
Innym przykładem jest próba zalogowania się użytkownika Britta Simon przy użyciu poniższej konfiguracji. Firma Microsoft Entra najpierw ocenia wszystkie warunki za pomocą źródła Attribute. Źródłem oświadczenia jest user.mail typ użytkownika Britta to goście firmy Microsoft Entra. Następnie identyfikator Entra firmy Microsoft ocenia przekształcenia. Ponieważ Britta jest gościem, user.extensionattribute1 jest nowym źródłem roszczenia. Ponieważ Britta jest w gości Microsoft Entra, user.othermail jest nowym źródłem tego oświadczenia. Na koniec oświadczenie jest emitowane z wartością user.othermail dla Britta.
W ostatnim przykładzie rozważmy, co się stanie, jeśli britta nie user.othermail ma skonfigurowanej lub jest pusta. Roszczenie powraca do user.extensionattribute1 ignorowania wpisu warunku w obu przypadkach.
Zagadnienia dotyczące zabezpieczeń
Aplikacje odbierające tokeny korzystają z wartości oświadczeń, których nie można manipulować. Podczas modyfikowania zawartości tokenu za pomocą dostosowywania oświadczeń te założenia mogą nie być już poprawne. Aplikacje muszą jawnie potwierdzić, że tokeny zostały zmodyfikowane, aby chronić się przed dostosowaniami utworzonymi przez złośliwych podmiotów. Ochrona przed nieodpowiednimi dostosowaniami w jeden z następujących sposobów:
- Konfigurowanie niestandardowego klucza podpisywania
- zaktualizuj manifest aplikacji, aby akceptował zamapowane oświadczenia.
Bez tego identyfikator Entra firmy Microsoft zwraca kod błędu AADSTS50146.
Konfigurowanie niestandardowego klucza podpisywania
W przypadku aplikacji wielodostępnych należy użyć niestandardowego klucza podpisywania. Nie ustawiaj acceptMappedClaims w manifeście aplikacji. Podczas konfigurowania aplikacji w witrynie Azure Portal uzyskujesz obiekt rejestracji aplikacji i jednostkę usługi w dzierżawie. Ta aplikacja używa klucza logowania globalnego platformy Azure, którego nie można używać do dostosowywania oświadczeń w tokenach. Aby uzyskać niestandardowe oświadczenia w tokenach, utwórz niestandardowy klucz logowania z certyfikatu i dodaj go do jednostki usługi. Do celów testowych można użyć certyfikatu z podpisem własnym. Po skonfigurowaniu niestandardowego klucza podpisywania kod aplikacji musi zweryfikować klucz podpisywania tokenu.
Dodaj następujące informacje do jednostki usługi:
- Klucz prywatny (jako poświadczenia klucza)
- Hasło (jako poświadczenie hasła)
- Klucz publiczny (jako poświadczenia klucza)
Wyodrębnij klucz prywatny i publiczny base-64 zakodowany z eksportu pliku PFX certyfikatu. Upewnij się, że keyId wartość dla elementu używanego keyCredential dla znaku jest zgodna keyId z wartością passwordCredential. Możesz wygenerować ten customkeyIdentifier element, uzyskując skrót odcisku palca certyfikatu.
Zażądaj
Uwaga
Najpierw wyłącz dowolną konfigurację blokady jednostki usługi w nowo utworzonych aplikacjach z bloku Rejestracje aplikacji Centrum administracyjnego firmy Microsoft przed podjęciem próby wykonania poprawki w jednostce usługi, co powoduje nieprawidłowe żądanie 400.
Poniższy przykład przedstawia format żądania HTTP PATCH w celu dodania niestandardowego klucza podpisywania do jednostki usługi. Wartość "klucz" we keyCredentials właściwości jest skracana do czytelności. Wartość jest zakodowana w formacie base-64. W przypadku klucza prywatnego użycie właściwości to Sign. W przypadku klucza publicznego użycie właściwości to Verify.
PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222
Content-type: servicePrincipals/json
Authorization: Bearer {token}
{
"keyCredentials":[
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "X509CertAndPassword",
"usage": "Sign",
"key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
"displayName": "CN=contoso"
},
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"endDateTime": "2021-04-22T22:10:13Z",
"keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
"startDateTime": "2020-04-22T21:50:13Z",
"type": "AsymmetricX509Cert",
"usage": "Verify",
"key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
"displayName": "CN=contoso"
}
],
"passwordCredentials": [
{
"customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
"keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
"endDateTime": "2022-01-27T19:40:33Z",
"startDateTime": "2020-04-20T19:40:33Z",
"secretText": "mypassword"
}
]
}
Konfigurowanie niestandardowego klucza podpisywania przy użyciu programu PowerShell
Użyj programu PowerShell, aby utworzyć wystąpienie publicznej aplikacji klienckiej MSAL i użyć przepływu udzielania kodu autoryzacji w celu uzyskania delegowanego tokenu dostępu uprawnień dla programu Microsoft Graph. Użyj tokenu dostępu, aby wywołać program Microsoft Graph i skonfigurować niestandardowy klucz podpisywania dla jednostki usługi. Po skonfigurowaniu niestandardowego klucza podpisywania kod aplikacji musi zweryfikować klucz podpisywania tokenu.
Aby uruchomić ten skrypt, potrzebne są następujące elementy:
- Identyfikator obiektu jednostki usługi aplikacji znajdujący się w bloku Przegląd wpisu aplikacji w aplikacjach dla przedsiębiorstw w witrynie Azure Portal.
- Rejestracja aplikacji w celu zalogowania użytkownika i uzyskania tokenu dostępu w celu wywołania programu Microsoft Graph. Pobierz identyfikator aplikacji (klienta) tej aplikacji w bloku Przegląd wpisu aplikacji w Rejestracje aplikacji w witrynie Azure Portal. Rejestracja aplikacji powinna mieć następującą konfigurację:
- Identyfikator URI przekierowania "http://localhost" wymienione w konfiguracji platformy aplikacje mobilne i klasyczne.
- W obszarze Uprawnienia interfejsu API delegowane uprawnienia programu Microsoft Graph Application.ReadWrite.All i User.Read (upewnij się, że udzielono zgody administratora na te uprawnienia).
- Użytkownik, który loguje się, aby uzyskać token dostępu programu Microsoft Graph. Użytkownik powinien być jedną z następujących ról administracyjnych firmy Microsoft Entra (wymagana do zaktualizowania jednostki usługi):
- Administrator aplikacji w chmurze
- Administrator aplikacji
- Certyfikat do skonfigurowania jako niestandardowy klucz podpisywania dla naszej aplikacji. Możesz utworzyć certyfikat z podpisem własnym lub uzyskać go z zaufanego urzędu certyfikacji. W skry skrycie są używane następujące składniki certyfikatu:
- klucz publiczny (zazwyczaj plik .cer )
- klucz prywatny w formacie PKCS#12 (w pliku pfx )
- hasło klucza prywatnego (plik pfx )
Ważne
Klucz prywatny musi być w formacie PKCS#12, ponieważ identyfikator Entra firmy Microsoft nie obsługuje innych typów formatów. Użycie nieprawidłowego formatu może spowodować błąd "Nieprawidłowy certyfikat: wartość klucza jest nieprawidłowa" w przypadku używania programu Microsoft Graph do poprawiania jednostki usługi zawierającej keyCredentials informacje o certyfikacie.
##########################################################
# Replace the variables below with the appropriate values
$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration
##########################################################
# Create a self-signed cert
$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile
$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd # password for the pfx file
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
if ($PSVersionTable.PSVersion.Major -gt 5)
{
$core = $true
}
else
{
$core = $false
}
# this is for PowerShell Core
$Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
# reading certificate files and creating Certificate Object
if ($core)
{
$pfx_cert = get-content $pfxpath -AsByteStream -Raw
$cer_cert = get-content $cerpath -AsByteStream -Raw
$cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
}
else
{
$pfx_cert = get-content $pfxpath -Encoding Byte
$cer_cert = get-content $cerpath -Encoding Byte
# calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
}
# base 64 encode the private key and public key
$base64pfx = [System.Convert]::ToBase64String($pfx_cert)
$base64cer = [System.Convert]::ToBase64String($cer_cert)
# getting id for the keyCredential object
$guid1 = New-Guid
$guid2 = New-Guid
# get the custom key identifier from the certificate thumbprint:
$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
$hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
$customKeyIdentifier = [System.Convert]::ToBase64String($hash)
# get end date and start date for our keycredentials
$endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
$startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
# building our json payload
$object = [ordered]@{
keyCredentials = @(
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
endDateTime = $endDateTime
keyId = $guid1
startDateTime = $startDateTime
type = "AsymmetricX509Cert"
usage = "Sign"
key = $base64pfx
displayName = "CN=$fqdn"
},
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
endDateTime = $endDateTime
keyId = $guid2
startDateTime = $startDateTime
type = "AsymmetricX509Cert"
usage = "Verify"
key = $base64cer
displayName = "CN=$fqdn"
}
)
passwordCredentials = @(
[ordered]@{
customKeyIdentifier = $customKeyIdentifier
displayName = "CN=$fqdn"
keyId = $guid1
endDateTime = $endDateTime
startDateTime = $startDateTime
secretText = $password
hint = $null
}
)
}
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object
$json = $object | ConvertTo-Json -Depth 99
Write-Host "JSON Payload:"
Write-Output $json
Weryfikowanie klucza podpisywania tokenu
Aplikacje z włączonym mapowaniem oświadczeń muszą zweryfikować klucze podpisywania tokenu, dołączając appid={client_id} je do żądań metadanych openID Connect. W poniższym przykładzie przedstawiono format dokumentu metadanych OpenID Connect, którego należy użyć:
https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}
Aktualizowanie manifestu aplikacji
W przypadku aplikacji z jedną dzierżawą acceptMappedClaims można ustawić właściwość na true w manifeście aplikacji. Zgodnie z dokumentacją apiApplication typu zasobu. Ustawienie właściwości umożliwia aplikacji używanie mapowania oświadczeń bez określania niestandardowego klucza podpisywania.
Ostrzeżenie
Nie należy ustawiać właściwości acceptMappedClaims na wartość true dla aplikacji wielodostępnych, co umożliwia złośliwym aktorom tworzenie zasad mapowania oświadczeń dla aplikacji.
Żądana grupa odbiorców tokenów jest wymagana do używania zweryfikowanej nazwy domeny dzierżawy firmy Microsoft Entra, co oznacza, że należy ustawić Application ID URI wartość (reprezentowaną przez identifierUris manifest aplikacji), na przykład na https://contoso.com/my-api lub (po prostu przy użyciu domyślnej nazwy dzierżawy). https://contoso.onmicrosoft.com/my-api
Jeśli nie używasz zweryfikowanej domeny, identyfikator Entra firmy Microsoft zwraca AADSTS501461 kod błędu z komunikatem "_AcceptMappedClaims jest obsługiwany tylko dla odbiorców tokenu pasujących do identyfikatora GUID aplikacji lub odbiorców w zweryfikowanych domenach dzierżawy. Zmień identyfikator zasobu lub użyj klucza podpisywania specyficznego dla aplikacji".
Zaawansowane opcje oświadczeń
Skonfiguruj zaawansowane opcje oświadczeń dla aplikacji OIDC, aby uwidocznić to samo oświadczenie co tokeny SAML. Ponadto w przypadku aplikacji, które zamierzają używać tego samego oświadczenia dla tokenów odpowiedzi SAML2.0 i OIDC.
Skonfiguruj zaawansowane opcje oświadczeń, zaznaczając pole wyboru w obszarze Zaawansowane opcje oświadczeń w bloku Zarządzanie oświadczeniami.
Powiązana zawartość
- Oświadczenia i tokeny używane w identyfikatorze Entra firmy Microsoft.