Provisioning Profile: چیست، چه انواعی دارد و چگونه کار می‌کند

Provisioning Profile چیست

Provisioning Profile یک فایل پیکربندی دیجیتال با فرمت .mobileprovision (برای iOS) یا .provisionprofile (برای macOS) است که اپل برای کنترل نصب و اجرای برنامه‌ها روی دستگاه‌ها از آن استفاده می‌کند. پروفایل حاوی فراداده‌های امضای کد است که بدون آن نمی‌توان برنامه را روی iPhone فیزیکی، iPad یا Apple Watch اجرا کرد — شبیه‌ساز به پروفایل نیازی ندارد، زیرا کد برای اجرا روی پردازنده واقعی امضا نمی‌شود.

پروفایل از طریق Apple Developer Portal صادر می‌شود و تاریخ انقضا دارد — معمولاً یک سال برای پروفایل‌های Development و Distribution. طبق سیاست اپل، پروفایل به‌طور خودکار با گواهی Apple Developer Program که زیر آن امضا شده مرتبط است: اگر گواهی لغو یا منقضی شود، پروفایل از کار می‌افتد.

هر پروفایل دارای UUID یکتاست که Xcode برای شناسایی پروفایل در زنجیره کلید از آن استفاده می‌کند. Xcode هنگام ساخت به‌طور خودکار پروفایل مناسب را انتخاب می‌کند، اما توسعه‌دهنده می‌تواند انتخاب را در تنظیمات Signing & Capabilities تغییر دهد. روی یک دستگاه می‌توان تعداد نامحدودی پروفایل نصب کرد — سیستم مدیریت دستگاه اپل (MDM) از این برای توزیع سازمانی برنامه‌ها استفاده می‌کند.

چرا Provisioning Profile لازم است

امضای کد دلیل اصلی وجود پروفایل‌هاست. اپل الزام می‌کند هر برنامه‌ای که روی دستگاه iOS اجرا می‌شود با گواهی صادرشده توسط اپل امضا شده باشد. Provisioning Profile نقش حلقه اتصال را ایفا می‌کند: تأیید می‌کند که توسعه‌دهنده حق اجرای برنامه روی این دستگاه را دارد. طبق Apple Security Guide (2025)، مکانیزم پروفایل‌ها حتی در صورت به خطر افتادن گواهی توسعه‌دهنده از نصب بدافزار روی دستگاه‌های کاربران جلوگیری می‌کند.

پروفایل همچنین تعیین می‌کند چه خدمات سیستمی برای برنامه در دسترس است. اگر برنامه از اعلان‌های Push استفاده می‌کند، Apple Push Notification service (APNs) به entitlements صحیح در داخل پروفایل نیاز دارد. بدون این، اعلان‌های سرور به دستگاه تحویل داده نمی‌شوند. قانون مشابهی برای iCloud، App Groups، Wallet، HealthKit و دیگر فریمورک‌های اپل اعمال می‌شود.

تفاوت با گواهی

توسعه‌دهندگان اغلب Provisioning Profile را با Apple Certificate اشتباه می‌گیرند. گواهی یک سند دیجیتال است که هویت را تأیید می‌کند (چه کسی امضا می‌کند)، در حالی که پروفایل یک پیکربندی است (کدام برنامه، روی کدام دستگاه‌ها، با چه حقوقی). یک گواهی می‌تواند در چند پروفایل استفاده شود و یک پروفایل دقیقاً به یک گواهی متصل است. اپل توصیه می‌کند برای هر برنامه و هر سناریو پروفایل جداگانه بسازید — Development، Ad Hoc، App Store.

Provisioning Profile چگونه کار می‌کند

فرآیند امضای برنامه از چند مرحله تشکیل شده که به‌صورت پیاپی انجام می‌شوند. Xcode فایل باینری برنامه (App Bundle) را می‌گیرد، آن را با کلید خصوصی توسعه‌دهنده امضا می‌کند، Provisioning Profile را در آن جاسازی می‌کند و به دستگاه می‌فرستد. دستگاه امضا را با کلید عمومی اپل بررسی می‌کند، UUID پروفایل را با فهرست پروفایل‌های معتمد در سیستم مقایسه می‌کند و فقط در صورت موفقیت همه بررسی‌ها برنامه را اجرا می‌کند.

وقتی کاربر برنامه را از App Store دانلود می‌کند، مکانیزم متفاوت است. App Store Connect برنامه را با گواهی Distribution خود اپل دوباره امضا می‌کند و پروفایل توسعه‌دهنده را با پروفایل Store جایگزین می‌کند. این بدان معناست که برنامه منتشرشده از طریق App Store از نظر فنی توسط اپل امضا شده، نه توسعه‌دهنده — اگرچه امضای اولیه توسعه‌دهنده در مرحله آپلود بیلد در App Store Connect بررسی می‌شود.

برای توزیع Ad Hoc، پروفایل UDID دستگاه‌های خاصی را ثبت می‌کند که اجرا روی آن‌ها مجاز است. حساب رایگان Apple Developer Program برای تست سالانه ۱۰۰ دستگاه محدودیت دارد. پروفایل‌های Enterprise (برای توزیع داخلی در سازمان) محدودیت تعداد دستگاه ندارند، اما نیازمند اشتراک فعال Apple Developer Enterprise Program با هزینه سالانه ۲۹۹ دلار هستند.

چرخه عمر پروفایل

مدت اعتبار Provisioning Profile از لحظه ایجاد یک سال است. ۳۰ روز قبل از انقضا، اپل شروع به ارسال اعلان‌های push به توسعه‌دهنده از طریق Xcode و Developer Portal می‌کند. اگر پروفایل منقضی شود، برنامه روی دستگاه به کار خود ادامه می‌دهد (اگر قبلاً نصب شده باشد)، اما بیلد جدید با این پروفایل قابل نصب نخواهد بود. Xcode هنگام تلاش برای ساخت با پروفایل منقضی خطای امضای کد با کد -402620394 می‌دهد. اپل توصیه می‌کند تمدید خودکار پروفایل‌ها را از طریق Xcode Accounts Preferences تنظیم کنید — در این صورت Xcode پروفایل را ۲۴ ساعت قبل از انقضا به‌روزرسانی می‌کند.

انواع Provisioning Profile

اپل چهار نوع اصلی Provisioning Profile ارائه می‌دهد که هر یک برای مرحله مشخصی از چرخه عمر برنامه طراحی شده‌اند. پروفایل Development امکان اجرای برنامه را روی دستگاه‌های فیزیکی که به Apple Developer Portal اضافه شده‌اند فراهم می‌کند و در مرحله توسعه و تست QA استفاده می‌شود. برای ایجاد پروفایل Development حساب رایگان توسعه‌دهنده اپل کافی است.

پروفایل Ad Hoc برای توزیع برنامه در میان گروه محدودی از تست‌کننده‌ها بدون استفاده از App Store طراحی شده است. پروفایل تا ۱۰۰ دستگاه را بر اساس UDID ثبت می‌کند و برنامه می‌تواند به‌طور مستقیم از طریق iTunes، Apple Configurator یا راه‌حل‌های MDM نصب شود. بیلدهای Ad Hoc مدت اعتبار ۱۲ ماه دارند و نیاز به گذراندن بازبینی اپل ندارند.

پروفایل App Store منحصراً برای انتشار برنامه در App Store استفاده می‌شود و فهرست دستگاه‌ها را ندارد — خود اپل پس از تأیید بیلد توزیع را مدیریت می‌کند. هنگام آپلود آرشیو در App Store Connect، Xcode اگر پروفایل App Store روی سیستم نصب باشد به‌طور خودکار از آن استفاده می‌کند. پروفایل Enterprise برای سازمان‌های دارای Apple Developer Enterprise Program طراحی شده و امکان توزیع برنامه‌ها در داخل شرکت بدون محدودیت تعداد دستگاه و بدون بازبینی اپل را فراهم می‌کند.

ساختار Provisioning Profile

Provisioning Profile فایلی با فرمت DER است که توسط اپل امضا شده و محتوای آن را می‌توان از طریق خط فرمان مشاهده کرد. Security framework سیستم macOS امکان رمزگشایی .mobileprovision به plist XML قابل‌خواندن را فراهم می‌کند. در داخل پروفایل موارد زیر قرار دارد: UUID پروفایل، App ID (پیشوند تیم + Bundle Identifier)، فهرست گواهی‌ها، فهرست دستگاه‌های مجاز (فقط برای Development و Ad Hoc)، entitlements و مدت اعتبار.

App ID — شناسه یکتای برنامه متشکل از Team ID (۱۰ کاراکتر که اپل تعیین می‌کند) و Bundle Identifier (مثلاً com.example.myapp). App ID می‌تواند explicit (تطابق دقیق با Bundle Identifier) یا wildcard (الگوی *.example.com برای چند برنامه) باشد. اپل استفاده از wildcard را برای برنامه‌هایی که از اعلان‌های Push یا iCloud استفاده می‌کنند توصیه نمی‌کند — این خدمات به App ID صریح نیاز دارند.

Entitlements — بلوک XML داخل پروفایل است که حقوق دسترسی برنامه به منابع سیستم را تعیین می‌کند. entitlements معمول شامل: aps-environment (اعلان‌های Push)، com.apple.developer.icloud-services (iCloud)، com.apple.security.application-groups (App Groups برای Widget و Share Extension). اپل بر اساس Capabilities فعال‌شده در Xcode به‌طور خودکار entitlements را به پروفایل اضافه می‌کند. هر ناهماهنگی بین entitlements پروفایل و موارد درخواستی در کد منجر به خطای امضا می‌شود.

ایجاد Provisioning Profile در Apple Developer

ایجاد پروفایل به دو روش امکان‌پذیر است: از طریق رابط وب Apple Developer Portal یا به‌طور خودکار از طریق Xcode. در پروژه معمولی وقتی گزینه Automatically manage signing فعال باشد Xcode پروفایل‌ها را به‌طور خودکار مدیریت می‌کند. Xcode در چند ثانیه گواهی، پروفایل و App ID ایجاد می‌کند و با Apple Developer Portal همگام‌سازی می‌شود. با این حال، برای پایپ‌لاین‌های CI/CD مدیریت دستی لازم است.

برای ایجاد دستی پروفایل در Apple Developer Portal باید: به بخش Certificates, Identifiers & Profiles بروید، Profiles را انتخاب کنید و روی «+» کلیک کنید. سپس نوع پروفایل را انتخاب کنید (Development، Ad Hoc، App Store یا Enterprise)، App ID را از فهرست ثبت‌شده انتخاب کنید، گواهی توسعه‌دهنده را انتخاب کنید و (برای Development و Ad Hoc) دستگاه‌ها را انتخاب کنید. پس از ایجاد، پروفایل با فرمت .mobileprovision دانلود و با دوبار کلیک در Xcode نصب می‌شود.

سرورهای CI/CD رویکرد خاصی می‌طلبند: پروفایل و گواهی باید در مخزن امن ذخیره شوند (مثلاً در secrets گیت‌هاب اکشنز). هنگام ساخت، پروفایل روی عامل بارگذاری می‌شود، در پوشه ~/Library/MobileDevice/Provisioning Profiles قرار می‌گیرد و گواهی به زنجیره کلید وارد می‌شود. Fastlane — ابزار محبوب برای خودکارسازی امضا — فرمان match را ارائه می‌دهد که پروفایل‌ها و گواهی‌ها را بین توسعه‌دهندگان از طریق مخزن git رمزگذاری‌شده همگام‌سازی می‌کند.

مثال: بررسی پروفایل از طریق خط فرمان

برای عیب‌یابی مشکلات امضای کد می‌توان .mobileprovision را رمزگشایی و محتوای آن را بررسی کرد. فرمان زیر plist XML را از پروفایل استخراج و در قالب خواندنی ذخیره می‌کند:

# رمزگشایی .mobileprovision به XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# بررسی مدت اعتبار پروفایل
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

ابزار Security از مجموعه macOS Command Line Tools فایل امضاشده CMS پروفایل را رمزگشایی می‌کند. پرچم -D به معنای رمزگشایی و -i فایل ورودی است. پس از رمزگشایی، ابزار plist باینری plist را به XML تبدیل می‌کند و grep تاریخ انقضا را استخراج می‌کند. این روش در CI/CD برای بررسی اینکه پروفایل قبل از ساخت نسخه نهایی منقضی نشده مفید است.

خطاهای رایج با Provisioning Profile

رایج‌ترین خطا «No matching provisioning profiles found» هنگام ساخت در Xcode است. این خطا وقتی رخ می‌دهد که Xcode نتواند پروفایلی منطبق با پیکربندی ساخت پیدا کند: Bundle Identifier با App ID پروفایل مطابقت ندارد، گواهی در زنجیره کلید نصب نیست یا پروفایل منقضی شده است. راه‌حل — تنظیمات Signing & Capabilities را در target بررسی کنید و در صورت لزوم به Automatically manage signing تغییر دهید.

خطای «Provisioning profile doesn't include the selected device» هنگام تلاش برای اجرای بیلد Development یا Ad Hoc روی دستگاهی که UDID آن به پروفایل اضافه نشده ظاهر می‌شود. Apple Developer Portal امکان افزودن دستگاه به پروفایل موجود را می‌دهد — پس از آن باید پروفایل را دوباره دانلود و نصب کنید. Xcode هنگام مدیریت خودکار امضا، دستگاه متصل را به‌طور خودکار به پروفایل اضافه می‌کند.

مشکل entitlements با خطای «The executable was signed with invalid entitlements» هنگام آپلود در App Store Connect ظاهر می‌شود. علت — عدم تطابق entitlements پروفایل با فایل .entitlements پروژه. اپل الزام می‌کند مجموعه حقوق پروفایل ابرمجموعه حقوق درخواستی برنامه باشد. راه‌حل — Capabilities را در target Xcode بررسی کنید و مطمئن شوید همه خدمات فعال دارای entitlements مربوطه در پروفایل هستند. Fastlane شامل فرمان produce است که App ID و پروفایل‌ها را با entitlements به‌روز همگام‌سازی می‌کند.