playfab service-principal command family is Experimental. Its CLI interface might
change or be removed based on feedback.
A continuous integration (CI) pipeline or other unattended job signs in as a Microsoft
Entra ID service principal; see
Automation (service principal) authentication.
PlayFab accepts the service principal only after a person grants it access in a PlayFab
studio. These commands manage those grants.
Only a signed-in person with Admin permission on the studio can run these commands. They
refuse to run when XBOX_AUTHENTICATION__MODE selects a service-principal mode, so sign in
with xbox auth login instead.
list accepts --output table; the other commands don’t. list returns one page: when
more exist, the response’s ContinuationToken is set, and running list again with
--continuation-token set to it gets the next page.
Identifiers
--studio-idnames the studio that owns the grants. These commands don’t take a PlayFab title, so--playfab-title-idand saved context don’t apply.--principal-tenant-idand--principal-object-ididentify the service principal: its Entra ID tenant, and the object ID of its enterprise application, not of its app registration.xbox auth statusreports it asobjectIdwhen signed in as the service principal.- You don’t pass the application (client) ID. PlayFab records it from the service
principal’s first token, and
listandgetreport it asClientId. - The global
--tenant-idand--client-idoptions configure your own sign-in, not the service principal you’re granting access to.
Grants file
Start from the current grants rather than writing a file from scratch. Save the output ofget, edit its StudioPermissions and TitleGrants, and pass it to set, with its
Version as --expected-version:
get, its data, the ServicePrincipal object
inside it, or only the grants:
- Both properties are required. An empty list grants nothing of that kind.
- Each title needs at least one permission. To remove a title’s grant, leave the title out.
- Property names aren’t case-sensitive. An unrecognized property is an error, so a
misspelled
TitleGrantscan’t remove every title grant. - The file’s
TenantId,ObjectId, andDisplayName, when present, must match--principal-tenant-id,--principal-object-id, and--display-name. To rename the service principal, changeDisplayNamein the file too, or remove it.
Expected version
Every change to a service principal’s grants gives them a newVersion, which get and
set return. With --expected-version, set changes nothing unless the grants are still
at that version, so it can’t undo a change someone made after you read them.
--expected-version 0 requires that the service principal has no access yet. Without
--expected-version, set replaces the grants whatever they are now.
When the grants file has a Version, --expected-version is required and must equal it.
If they differ, run get again and redo your edits on its output. To replace the grants
regardless, remove Version from the file and leave out --expected-version.
If set fails
A failure doesn’t say whether the grants changed, so don’t run set again with the old
version. Run get, check its grants and Version, and if they aren’t what you meant to
set, edit that output and pass it to set with its Version as --expected-version.
Examples
List a studio’s service principals, and show one’s grants:grants.json, which you saved from
get and edited:
revoke, the service principal’s next PlayFab request in the studio fails. revoke
also succeeds when the service principal already has no access. To restore access, run
set with the complete grant set.