صدور مجوز

برنامه‌ها بااستفاده از OAuth، تماس‌ها با میانای برنامه‌سازی کاربردی مشتری ثبت‌نام تمام‌خودکار را مجاز می‌کنند. این سند مجوز میانای برنامه‌سازی کاربردی را برای ارائه‌دهندگان مدیریت پویایی سازمانی (EMM) و توسعه‌دهندگان فناوری اطلاعات سازمانی توضیح می‌دهد. پس‌از خواندن این سند، با نحوه صدور مجوز برای درخواست‌های API در برنامه‌تان آشنا خواهید شد و می‌توانید الزامات حساب را برای کاربران برنامه‌تان توضیح دهید.

شروع سریع صدور مجوز

  • برای راه‌اندازی پروژه Google Cloud Platform با API ثبت‌نام تمام خودکار و رمزهای کارخواه OAuth، این جادوگر را اجرا کنید.
  • کد نمونه شروع سریع را برای Java،‏ NET.، یا Python بسازید. از کتابخانه‌های کارخواه میانای برنامه‌سازی کاربردی Google برای پشتیبانی از زبان‌های دیگر استفاده کنید.

نمای کلی

رابطه دستگاه و منبع مشتری

  1. یک یا چند سرپرست فناوری اطلاعات در حساب مشتری ثبت‌نام تمام خودکار کاربر هستند.
  2. سرپرستان فناوری اطلاعات از «حساب Google» برای اصالت‌سنجی خودشان استفاده می‌کنند.
  3. درخواست‌های API یک کد OAuth2 را برای صدور مجوز درخواست‌های API ازطرف سرپرست فناوری اطلاعات ارسال می‌کنند.

حساب‌های مشتری

پیکربندی‌ها، دستگاه‌ها، و کاربران (سرپرست فناوری اطلاعات) سازمان به یک حساب مشتری تعلق دارند. حساب مشتری شبیه به گروه است و کاربر فردی نیست. وقتی سازمان برای اولین‌بار دستگاه‌هایی را برای ثبت‌نام تمام خودکار خریداری می‌کند، فروشنده مشتری را راه‌اندازی می‌کند. سرپرستان فناوری اطلاعات کاربران دیگر را در سازمانشان بااستفاده از درگاه ثبت‌نام تمام‌خودکار مدیریت می‌کنند.

این میانای برنامه‌سازی کاربردی از شناسه‌های مشتری عددی برای شناسایی حساب‌ها استفاده می‌کند. هنگام فراخوانی روش‌های میانای برنامه‌سازی کاربردی، شناسه مشتری را به‌عنوان بخشی از مسیر نشانی وب ارسال می‌کنید. برنامه شما باید قبل‌از فراخوانی هرگونه روش میانای برنامه‌سازی کاربردی، شناسه مشتری کاربر را دریافت کند.

مثال زیر نشان می‌دهد که چگونه حساب‌های مشتری را برای کاربری که فراخوانی میانای برنامه‌سازی کاربردی را مجاز می‌کند دریافت کنید:

جاوا

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

دات نت

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

در برنامه‌تان، باید در صفحه‌های نتایج حساب پیمایش کنید زیرا نمونه بالا فقط ۱۰۰ حساب اول را چاپ می‌کند. برای آشنایی با نحوه انجام این کار، نتایج صفحه‌بندی‌شده را بخوانید.

سازمان معمولاً یک حساب مشتری دارد اما سازمان‌های بزرگ‌تر ممکن است برای هر بخش از حساب‌های مشتری جداگانه‌ای استفاده کنند. چون سرپرست فناوری اطلاعات می‌تواند عضو حساب‌های مشتری مختلفی باشد، برنامه‌تان باید به کاربران کمک کند حساب‌های مشتری جدید را پیدا و استفاده کنند. در برنامه‌تان، هر حساب مشتری را بااستفاده از مقدار companyName برچسب‌گذاری کنید.

کاربران

سرپرستان فناوری اطلاعات درخواست‌های میانای برنامه‌سازی کاربردی را که برنامه‌تان ازطرف آن‌ها ارسال می‌کند مجاز می‌کنند. برای مجاز کردن درخواست‌های میانای برنامه‌سازی کاربردی، کاربر برنامه شما باید کارهای زیر را انجام دهد:

  1. «حساب Google» را با نشانی ایمیل او مرتبط کنید.
  2. بااستفاده از همان نشانی ایمیل به حساب مشتری بپیوندید.
  3. «شرایط خدمات» مشتری ثبت‌نام تمام خودکار را بپذیرید.

برای کمک به راه‌اندازی کاربران برنامه‌تان، از راهنمای ما برای سرپرستان فناوری اطلاعات در شروع به کار و مرتبط کردن «حساب Google» در اسناد خودتان استفاده کنید.

مدیریت کاربر

سرپرستان فناوری اطلاعات کاربران حساب‌های مشتری خود را در درگاه ثبت‌نام تمام‌خودکار مدیریت می‌کنند. کاربران در حساب مشتری نقشی دارند که یا مالک است یا سرپرست. هر دو نقش دسترسی یکسانی به میانای برنامه‌سازی کاربردی مشتری دارند اما مالک می‌تواند کاربران دیگر را مدیریت کند.

پذیرش شرایط خدمات

قبل‌از اینکه کاربران برنامه‌تان بتوانند تماس‌های میانای برنامه‌سازی کاربردی را مجاز کنند، باید جدیدترین شرایط خدمات را بپذیرند. این اتفاق زمانی می‌افتد که سرپرستان فناوری اطلاعات برای اولین‌بار از ثبت‌نام تمام خودکار استفاده می‌کنند یا زمانی که ما شرایط خدمات را به‌روز می‌کنیم. وقتی کاربری جدیدترین «شرایط خدمات» را نپذیرفته باشد، میانای برنامه‌سازی کاربردی رمز وضعیت HTTP 403 Forbidden را برمی‌گرداند و بدنه پاسخ حاوی TosError است.

وقتی کاربران به سیستم وارد می‌شوند، درگاه به‌طور خودکار از آن‌ها می‌خواهد جدیدترین «شرایط خدمات» را بپذیرند. برای دیدن رویکردهای پیشنهادی که برنامه‌تان می‌تواند شامل شود، مدیریت شرایط خدمات را در راهنمای ادغام EMM بخوانید.

 افزودن مجوز به برنامه

هر درخواستی که برنامه‌تان به API مشتری ارسال می‌کند باید حاوی یک کد مجازسازی باشد. این کد همچنین برنامه شما را برای Google شناسایی می‌کند. چون میانای برنامه‌سازی کاربردی مشتری به داده‌های کاربر دسترسی دارد، مجوز باید ازسوی مالک داده‌ها صادر شود. برنامه شما بااستفاده از پروتکل OAuth 2.0، مجوز میانای برنامه‌سازی کاربردی را به سرپرستان فناوری اطلاعات واگذار می‌کند.

دستورالعمل‌ها

ما راهنماهای شروع سریع برای برنامه‌های Java،‏ .NET، و Python ارائه می‌دهیم. اگر از زبان دیگری استفاده می‌کنید، دو مرحله زیر را برای راه‌اندازی مجوز برای برنامه‌تان دنبال کنید.

برای کسب اطلاعات بیشتر درباره صدور مجوز، استفاده از OAuth 2.0 برای دسترسی به Google APIs را بخوانید.

دامنه‌های مجوز

از محدوده مجوز میانای برنامه‌سازی کاربردی https://www.googleapis.com/auth/androidworkzerotouchemm در برنامه‌تان برای درخواست کد دسترسی OAuth 2.0 استفاده کنید.

پارامتر حوزه مجموعه منابع و عملیاتی را که کد دسترسی اجازه فراخوانی آن‌ها را می‌دهد کنترل می‌کند. کدهای دسترسی فقط برای مجموعه عملیات‌ها و منابع شرح‌داده‌شده در دامنه درخواست کد معتبر هستند. این میانای برنامه‌سازی کاربردی همه روش‌ها و منابع را با یک دامنه ثبت‌نام تمام‌خودکار که در بالا نشان داده شده است پوشش می‌دهد.

برای نمونه‌ای از دامنه ثبت‌نام تمام خودکار که با کتابخانه کارخواه Google API استفاده می‌شود، به شروع سریع برای Java، .NET، و Python مراجعه کنید. برای کسب اطلاعات بیشتر درباره استفاده از گستره‌های Google API، مقاله استفاده از OAuth 2.0 برای دسترسی به Google API را بخوانید.

روال‌های مطلوب برای کلیدهای میانای برنامه‌سازی کاربردی

وقتی از کلیدهای میانای API در برنامه‌هایتان استفاده می‌کنید، مراقب باشید که آن‌ها را ایمن نگه دارید. افشای عمومی اطلاعات اعتباری‌تان می‌تواند منجر به لورفتن حسابتان شود که این امر می‌تواند هزینه‌های غیرمنتظره‌ای را برای حسابتان به‌همراه داشته باشد. برای حفظ امنیت کلیدهای میانای API، این روال‌های مطلوب را دنبال کنید:

کلیدهای میانای API را مستقیماً در کد جاسازی نکنید
کلیدهای میانای برنامه‌سازی کاربردی که در کد جاسازی شده‌اند ممکن است به‌طور تصادفی درمعرض دید عموم قرار بگیرند—برای مثال، اگر فراموش کنید کلیدها را از کدی که هم‌رسانی می‌کنید بردارید. به‌جای جاسازی کردن کلیدهای میانای برنامه‌سازی کاربردی در برنامه‌هایتان، آن‌ها را در متغیرهای محیطی یا در فایل‌های خارج از درخت منبع برنامه‌تان ذخیره کنید.
کلیدهای میانای برنامه‌سازی کاربردی را در فایل‌های داخل درخت منبع برنامه‌تان ذخیره نکنید
اگر کلیدهای میانای برنامه‌سازی کاربردی را در فایل‌ها ذخیره می‌کنید، فایل‌ها را خارج از درخت منبع برنامه‌تان نگه دارید تا مطمئن شوید کلیدهایتان در سیستم کنترل کد منبع قرار نمی‌گیرند. این موضوع به‌ویژه زمانی اهمیت دارد که از سیستم مدیریت کد منبع عمومی مانند GitHub استفاده می‌کنید.
کلیدهای میانای API خود را محدود کنید تا فقط توسط نشانی‌های IP، نشانی‌های وب ارجاع‌دهنده، و برنامه‌های تلفن همراهی که به آن‌ها نیاز دارند استفاده شوند
با محدود کردن نشانی‌های IP، نشانی‌های وب ارجاع‌دهنده، و برنامه‌های تلفن همراهی که می‌توانند از هر کلید استفاده کنند، می‌توانید تأثیر کلید API لو رفته را کاهش دهید. می‌توانید میزبان‌ها و برنامه‌هایی را که می‌توانند از هر کلید استفاده کنند در کنسول Google API مشخص کنید. برای این کار، صفحه اطلاعات کاربری را باز کنید و سپس کلید API جدیدی با تنظیمات موردنظرتان ایجاد کنید یا تنظیمات کلید API را ویرایش کنید.
حذف کلیدهای میانای برنامه‌سازی کاربردی غیرضروری
برای به‌حداقل رساندن احتمال حمله، کلیدهای میانای API را که دیگر نیاز ندارید حذف کنید.
کلیدهای میانای برنامه‌سازی کاربردی را به‌طور دوره‌ای بازتولید کنید
می‌توانید کلیدهای میانای برنامه‌سازی کاربردی را از کنسول Google API با باز کردن صفحه اطلاعات کاربری، انتخاب کلید میانای برنامه‌سازی کاربردی، و کلیک کردن روی بازتولید کلید برای هر کلید، بازتولید کنید. سپس برنامه‌هایتان را به‌روز کنید تا از کلیدهای جدیداً تولیدشده استفاده کنند. کلیدهای قدیمی‌تان تا ۲۴ ساعت پس‌از تولید کلیدهای جایگزین همچنان کار خواهند کرد.
پیش‌از انتشار عمومی کد، آن را مرور کنید
پیش‌از اینکه کدتان را دردسترس عموم قرار دهید، مطمئن شوید که کدتان حاوی کلیدهای میانای برنامه‌سازی کاربردی یا هرگونه اطلاعات خصوصی دیگر نباشد.